path: root/docs/reference/pygio-fileenumerator.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-giofileenumerator">
    <refnamediv>
        <refname>gio.FileEnumerator</refname>
        <refpurpose>Enumerated Files Routines.</refpurpose>
    </refnamediv>

    <refsect1>
        <title>Synopsis</title>

    <classsynopsis language="python">
        <ooclass><classname>gio.FileEnumerator</classname></ooclass>
        <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
    
    <methodsynopsis language="python">
        <methodname><link linkend="method-giofileenumerator--close">close</link></methodname>
        <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giofileenumerator--close-async">close_async</link></methodname>
        <methodparam><parameter role="keyword">callback</parameter></methodparam>
        <methodparam><parameter role="keyword">io_priority</parameter><initializer><literal>glib.PRIORITY_DEFAULT</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-giofileenumerator--close-finish">close_finish</link></methodname>
        <methodparam><parameter role="keyword">result</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giofileenumerator--get-container">get_container</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giofileenumerator--has-pending">has_pending</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giofileenumerator--is-closed">is_closed</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giofileenumerator--next-file">next_file</link></methodname>
        <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giofileenumerator--next-files-async">next_files_async</link></methodname>
        <methodparam><parameter role="keyword">num_files</parameter></methodparam>
        <methodparam><parameter role="keyword">callback</parameter></methodparam>
        <methodparam><parameter role="keyword">io_priority</parameter><initializer><literal>glib.PRIORITY_DEFAULT</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-giofileenumerator--next-files-finish">next_files_finish</link></methodname>
        <methodparam><parameter role="keyword">result</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-giofileenumerator--set-pending">set_pending</link></methodname>
        <methodparam><parameter role="keyword">pending</parameter></methodparam>
    </methodsynopsis>
    
    </classsynopsis>

    </refsect1>

    <refsect1>
        <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-giofileenumerator">gio.FileEnumerator</link>
</synopsis>

    </refsect1>

    <refsect1 id="properties-giofileenumerator">
        <title>gio.FileEnumerator Properties</title>
    
        <blockquote role="properties">
            <informaltable pgwide="1" frame="none">
                <tgroup cols="3">
                    <colspec column="1" colwidth="1in"/>
                    <colspec column="2" colwidth="1in"/>
                    <colspec column="3" colwidth="4in"/>
                    <tbody>
                        <row valign="top">
                            <entry>"container"</entry>
                            <entry>Write - Construct only</entry>
                            <entry>The container that is being enumerated.</entry>
                        </row>
                    </tbody>
                </tgroup>
            </informaltable>
        </blockquote>
  
    </refsect1>

    <refsect1>
        <title>Description</title>

        <para>
            The <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link>
            allows you to operate on a set of
            <link linkend="class-giofile"><classname>gio.File</classname></link>s
            returning a
            <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
            structure for each file enumerated (e.g.
            <methodname><link linkend="method-giofile--enumerate-children">gio.File.enumerate_children</link></methodname>()
            will return a The <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link>
            for each of the children within a directory).
        </para>
        <para>
            To get the next file's information from a
            The <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link> use
            <methodname><link linkend="method-giofileenumerator--next-file">gio.FileEnumerator.next_file</link></methodname>()
            or its asynchronous version,
            <methodname><link linkend="method-giofileenumerator--next-files-async">gio.FileEnumerator.next_files_async</link></methodname>().
            Note that the asynchronous version will return a list of
            <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>s,
            whereas the synchronous will only return the next file in the enumerator. 
        </para>
        <para>
            To close a <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link>
            use <methodname><link linkend="method-giofileenumerator--close">close</link></methodname>,
            or its asynchronous version,
            <methodname><link linkend="method-giofileenumerator--close-async">close_async</link></methodname>.
            Once a <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link>
            is closed, no further actions may be performed on it.
        </para>
    </refsect1>

    <refsect1>
        <title>Methods</title>

        <refsect2 id="method-giofileenumerator--close">
            <title>gio.FileEnumerator.close</title>

            <programlisting><methodsynopsis language="python">
                <methodname>close</methodname>
                <methodparam>
                    <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer>
                </methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <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><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara><literal>True</literal> on success or
                    <literal>False</literal> on error. 
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>close</methodname>() method releases all resources used by this
                enumerator, making the
                <xref linkend="gio-error-constants" endterm="gio-error-constants-title"></xref>
                return gio.ERROR_CLOSED on all calls. 
            </para>
            <para>
                This will be automatically called when the last reference is dropped,
                but you might want to call this function to make sure resources are released
                as early as possible.
            </para>
        </refsect2>

        <refsect2 id="method-giofileenumerator--close-async">
            <title>gio.FileEnumerator.close_async</title>

            <programlisting><methodsynopsis language="python">
                <methodname>close_async</methodname>
                <methodparam>
                    <parameter role="keyword">callback</parameter>
                </methodparam>
                <methodparam>
                    <parameter role="keyword">io_priority</parameter><initializer><literal>glib.PRIORITY_DEFAULT</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">io_priority</parameter>&nbsp;:</term>
                  <listitem><simpara>The
                  <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> of the request. 
                  </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>close_async</methodname>() method asynchronously closes the file enumerator. 
            </para>
            <para>
                If cancellable is not <literal>None</literal>, then the operation can be cancelled by
                triggering the cancellable object from another thread. If the operation was cancelled,
                the error gio.ERROR_CANCELLED will be returned in
                <methodname><link linkend="method-giofileenumerator--close-finish">gio.FileEnumerator.close_finish</link></methodname>().
            </para>
        </refsect2>

        <refsect2 id="method-giofileenumerator--close-finish">
            <title>gio.FileEnumerator.close_finish</title>

            <programlisting><methodsynopsis language="python">
                <methodname>close_finish</methodname>
                <methodparam><parameter role="keyword">result</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">result</parameter>&nbsp;:</term>
                  <listitem><simpara>a GAsyncResult.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara><literal>True</literal> if the close operation
                    has finished successfully.</simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>close_finish</methodname>() method finishes closing a file enumerator, started from
                <methodname><link linkend="method-giofileenumerator--close-async">gio.FileEnumerator.close_async</link></methodname>(). 
            </para>
            <para>
                If the file enumerator was already closed when
                <methodname><link linkend="method-giofileenumerator--close-async">gio.FileEnumerator.close_async</link></methodname>()
                was called, then this function will report gio.ERROR_CLOSED in error, and return <literal>False</literal>.
                If the file enumerator had pending operation when the close operation was started, then this function will report
                gio.ERROR_PENDING, and return <literal>False</literal>. If cancellable was not <literal>None</literal>, then the operation
                may have been cancelled by triggering the cancellable object from another thread. If the operation was cancelled,
                the error gio.ERROR_CANCELLED will be set, and <literal>False</literal> will be returned.
            </para>
        </refsect2>

        <refsect2 id="method-giofileenumerator--get-container">
            <title>gio.FileEnumerator.get_container</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_container</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>the <link linkend="class-giofile"><classname>gio.File</classname></link>
                    which is being enumerated. </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>get_container</methodname>() method gets the
                <link linkend="class-giofile"><classname>gio.File</classname></link>
                container which is being enumerated.
            </para>
        </refsect2>

        <refsect2 id="method-giofileenumerator--has-pending">
            <title>gio.FileEnumerator.has_pending</title>

            <programlisting><methodsynopsis language="python">
                <methodname>has_pending</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
            <varlistentry>
                <term><emphasis>Returns</emphasis>&nbsp;:</term>
                <listitem><simpara><literal>True</literal> if the enumerator has pending operations.</simpara></listitem>
            </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>has_pending</methodname>() method checks if the file enumerator has pending operations.
            </para>
        </refsect2>

        <refsect2 id="method-giofileenumerator--is-closed">
            <title>gio.FileEnumerator.is_closed</title>

            <programlisting><methodsynopsis language="python">
                <methodname>is_closed</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara><literal>True</literal> if the enumerator is closed.</simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>is_closed</methodname>() method checks if the file enumerator has been closed.
            </para>
        </refsect2>

        <refsect2 id="method-giofileenumerator--next-file">
            <title>gio.FileEnumerator.next_file</title>

            <programlisting><methodsynopsis language="python">
                <methodname>next_file</methodname>
                <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <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><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>A <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
                    or <literal>None</literal> on error or end of enumerator.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>next_file</methodname>() method returns information for the next
                file in the enumerated object. Will block until the information is available.
                The <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
                returned from this function will contain attributes that match the attribute string
                that was passed when the GFileEnumerator was created. 
            </para>
            <para>
                On error, returns <literal>None</literal> and sets error to the error. If the enumerator
                is at the end, <literal>None</literal> will be returned and error will be unset.
            </para>
        </refsect2>

        <refsect2 id="method-giofileenumerator--next-files-async">
            <title>gio.FileEnumerator.next_files_async</title>

            <programlisting><methodsynopsis language="python">
                <methodname>next_files_async</methodname>
                <methodparam><parameter role="keyword">num_files</parameter></methodparam>
                <methodparam><parameter role="keyword">callback</parameter></methodparam>
                <methodparam>
                    <parameter role="keyword">io_priority</parameter><initializer><literal>glib.PRIORITY_DEFAULT</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">num_files</parameter>&nbsp;:</term>
                  <listitem><simpara>The number of file info objects to request.
                  </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">io_priority</parameter>&nbsp;:</term>
                  <listitem><simpara>The
                  <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> of the request. 
                  </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>next_files_async</methodname>() method requests information for a number
                of files from the enumerator asynchronously. When all i/o for the operation is finished
                the callback will be called with the requested information. 
            </para>
            <para>
                The callback can be called with less than num_files files in case of error or at the
                end of the enumerator. In case of a partial error the callback will be called with any
                succeeding items and no error, and on the next request the error will be reported. If a
                request is cancelled the callback will be called with gio.ERROR_CANCELLED. 
            </para>
            <para>
                During an async request no other sync and async calls are allowed, and will result in gio.ERROR_PENDING errors. 
            </para>
            <para>
                Any outstanding i/o request with higher priority (lower numerical value) will be executed
                before an outstanding request with lower priority. Default priority is glib.PRIORITY_DEFAULT.
            </para>
        </refsect2>

        <refsect2 id="method-giofileenumerator--next-files-finish">
            <title>gio.FileEnumerator.next_files_finish</title>

            <programlisting><methodsynopsis language="python">
                <methodname>next_files_finish</methodname>
                <methodparam><parameter role="keyword">result</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">result</parameter>&nbsp;:</term>
                  <listitem><simpara>a GAsyncResult.
                  </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                    <listitem><simpara>A list of
                    <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>s.
                    </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>next_files_finish</methodname>() method finishes the
                asynchronous operation started with
                <methodname><link linkend="method-giofileenumerator--next-files-async">gio.FileEnumerator.next_files_async</link></methodname>().
            </para>
        </refsect2>

        <refsect2 id="method-giofileenumerator--set-pending">
            <title>gio.FileEnumerator.set_pending</title>

            <programlisting><methodsynopsis language="python">
                <methodname>set_pending</methodname>
                <methodparam><parameter role="keyword">pending</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                  <term><parameter role="keyword">pending</parameter>&nbsp;:</term>
                  <listitem><simpara>A boolean value.
                  </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <para>
                The <methodname>push_current</methodname>() method sets the file enumerator as having pending operations.
            </para>
        </refsect2>
    </refsect1>
</refentry>