docs/reference/pygio-fileenumerator.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-giofileenumerator">
   6     <refnamediv>
   7         <refname>gio.FileEnumerator</refname>
   8         <refpurpose>Enumerated Files Routines.</refpurpose>
   9     </refnamediv>
  10
  11     <refsect1>
  12         <title>Synopsis</title>
  13
  14     <classsynopsis language="python">
  15         <ooclass><classname>gio.FileEnumerator</classname></ooclass>
  16         <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
  17
  18     <methodsynopsis language="python">
  19         <methodname><link linkend="method-giofileenumerator--close">close</link></methodname>
  20         <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
  21     </methodsynopsis>
  22     <methodsynopsis language="python">
  23         <methodname><link linkend="method-giofileenumerator--close-async">close_async</link></methodname>
  24         <methodparam><parameter role="keyword">callback</parameter></methodparam>
  25         <methodparam><parameter role="keyword">io_priority</parameter><initializer><literal>glib.PRIORITY_DEFAULT</literal></initializer></methodparam>
  26         <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
  27         <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam>
  28     </methodsynopsis>
  29     <methodsynopsis language="python">
  30         <methodname><link linkend="method-giofileenumerator--close-finish">close_finish</link></methodname>
  31         <methodparam><parameter role="keyword">result</parameter></methodparam>
  32     </methodsynopsis>
  33     <methodsynopsis language="python">
  34         <methodname><link linkend="method-giofileenumerator--get-container">get_container</link></methodname>
  35         <methodparam></methodparam>
  36     </methodsynopsis>
  37     <methodsynopsis language="python">
  38         <methodname><link linkend="method-giofileenumerator--has-pending">has_pending</link></methodname>
  39         <methodparam></methodparam>
  40     </methodsynopsis>
  41     <methodsynopsis language="python">
  42         <methodname><link linkend="method-giofileenumerator--is-closed">is_closed</link></methodname>
  43         <methodparam></methodparam>
  44     </methodsynopsis>
  45     <methodsynopsis language="python">
  46         <methodname><link linkend="method-giofileenumerator--next-file">next_file</link></methodname>
  47         <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
  48     </methodsynopsis>
  49     <methodsynopsis language="python">
  50         <methodname><link linkend="method-giofileenumerator--next-files-async">next_files_async</link></methodname>
  51         <methodparam><parameter role="keyword">num_files</parameter></methodparam>
  52         <methodparam><parameter role="keyword">callback</parameter></methodparam>
  53         <methodparam><parameter role="keyword">io_priority</parameter><initializer><literal>glib.PRIORITY_DEFAULT</literal></initializer></methodparam>
  54         <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
  55         <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam>
  56     </methodsynopsis>
  57     <methodsynopsis language="python">
  58         <methodname><link linkend="method-giofileenumerator--next-files-finish">next_files_finish</link></methodname>
  59         <methodparam><parameter role="keyword">result</parameter></methodparam>
  60     </methodsynopsis>
  61     <methodsynopsis language="python">
  62         <methodname><link linkend="method-giofileenumerator--set-pending">set_pending</link></methodname>
  63         <methodparam><parameter role="keyword">pending</parameter></methodparam>
  64     </methodsynopsis>
  65
  66     </classsynopsis>
  67
  68     </refsect1>
  69
  70     <refsect1>
  71         <title>Ancestry</title>
  72
  73 <synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  74   +-- <link linkend="class-giofileenumerator">gio.FileEnumerator</link>
  75 </synopsis>
  76
  77     </refsect1>
  78
  79     <refsect1 id="properties-giofileenumerator">
  80         <title>gio.FileEnumerator Properties</title>
  81
  82         <blockquote role="properties">
  83             <informaltable pgwide="1" frame="none">
  84                 <tgroup cols="3">
  85                     <colspec column="1" colwidth="1in"/>
  86                     <colspec column="2" colwidth="1in"/>
  87                     <colspec column="3" colwidth="4in"/>
  88                     <tbody>
  89                         <row valign="top">
  90                             <entry>"container"</entry>
  91                             <entry>Write - Construct only</entry>
  92                             <entry>The container that is being enumerated.</entry>
  93                         </row>
  94                     </tbody>
  95                 </tgroup>
  96             </informaltable>
  97         </blockquote>
  98
  99     </refsect1>
 100
 101     <refsect1>
 102         <title>Description</title>
 103
 104         <para>
 105             The <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link>
 106             allows you to operate on a set of
 107             <link linkend="class-giofile"><classname>gio.File</classname></link>s
 108             returning a
 109             <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
 110             structure for each file enumerated (e.g.
 111             <methodname><link linkend="method-giofile--enumerate-children">gio.File.enumerate_children</link></methodname>()
 112             will return a The <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link>
 113             for each of the children within a directory).
 114         </para>
 115         <para>
 116             To get the next file's information from a
 117             The <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link> use
 118             <methodname><link linkend="method-giofileenumerator--next-file">gio.FileEnumerator.next_file</link></methodname>()
 119             or its asynchronous version,
 120             <methodname><link linkend="method-giofileenumerator--next-files-async">gio.FileEnumerator.next_files_async</link></methodname>().
 121             Note that the asynchronous version will return a list of
 122             <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>s,
 123             whereas the synchronous will only return the next file in the enumerator.
 124         </para>
 125         <para>
 126             To close a <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link>
 127             use <methodname><link linkend="method-giofileenumerator--close">close</link></methodname>,
 128             or its asynchronous version,
 129             <methodname><link linkend="method-giofileenumerator--close-async">close_async</link></methodname>.
 130             Once a <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link>
 131             is closed, no further actions may be performed on it.
 132         </para>
 133     </refsect1>
 134
 135     <refsect1>
 136         <title>Methods</title>
 137
 138         <refsect2 id="method-giofileenumerator--close">
 139             <title>gio.FileEnumerator.close</title>
 140
 141             <programlisting><methodsynopsis language="python">
 142                 <methodname>close</methodname>
 143                 <methodparam>
 144                     <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer>
 145                 </methodparam>
 146             </methodsynopsis></programlisting>
 147
 148             <variablelist>
 149                 <varlistentry>
 150                   <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
 151                   <listitem><simpara>Optional
 152                   <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
 153                   object, <literal>None</literal> to ignore.
 154                   </simpara></listitem>
 155                 </varlistentry>
 156                 <varlistentry>
 157                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 158                     <listitem><simpara><literal>True</literal> on success or
 159                     <literal>False</literal> on error.
 160                     </simpara></listitem>
 161                 </varlistentry>
 162             </variablelist>
 163
 164             <para>
 165                 The <methodname>close</methodname>() method releases all resources used by this
 166                 enumerator, making the
 167                 <xref linkend="gio-error-constants" endterm="gio-error-constants-title"></xref>
 168                 return gio.ERROR_CLOSED on all calls.
 169             </para>
 170             <para>
 171                 This will be automatically called when the last reference is dropped,
 172                 but you might want to call this function to make sure resources are released
 173                 as early as possible.
 174             </para>
 175         </refsect2>
 176
 177         <refsect2 id="method-giofileenumerator--close-async">
 178             <title>gio.FileEnumerator.close_async</title>
 179
 180             <programlisting><methodsynopsis language="python">
 181                 <methodname>close_async</methodname>
 182                 <methodparam>
 183                     <parameter role="keyword">callback</parameter>
 184                 </methodparam>
 185                 <methodparam>
 186                     <parameter role="keyword">io_priority</parameter><initializer><literal>glib.PRIORITY_DEFAULT</literal></initializer>
 187                 </methodparam>
 188                 <methodparam>
 189                     <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer>
 190                 </methodparam>
 191                 <methodparam>
 192                     <parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer>
 193                 </methodparam>
 194             </methodsynopsis></programlisting>
 195
 196             <variablelist>
 197                 <varlistentry>
 198                   <term><parameter role="keyword">callback</parameter>&nbsp;:</term>
 199                   <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied.
 200                   </simpara></listitem>
 201                 </varlistentry>
 202                 <varlistentry>
 203                   <term><parameter role="keyword">io_priority</parameter>&nbsp;:</term>
 204                   <listitem><simpara>The
 205                   <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> of the request.
 206                   </simpara></listitem>
 207                 </varlistentry>
 208                 <varlistentry>
 209                   <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
 210                   <listitem><simpara>Optional
 211                   <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
 212                   object, <literal>None</literal> to ignore.
 213                   </simpara></listitem>
 214                 </varlistentry>
 215                 <varlistentry>
 216                   <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
 217                   <listitem><simpara>The data to pass to callback function.
 218                   </simpara></listitem>
 219                 </varlistentry>
 220             </variablelist>
 221
 222             <para>
 223                 The <methodname>close_async</methodname>() method asynchronously closes the file enumerator.
 224             </para>
 225             <para>
 226                 If cancellable is not <literal>None</literal>, then the operation can be cancelled by
 227                 triggering the cancellable object from another thread. If the operation was cancelled,
 228                 the error gio.ERROR_CANCELLED will be returned in
 229                 <methodname><link linkend="method-giofileenumerator--close-finish">gio.FileEnumerator.close_finish</link></methodname>().
 230             </para>
 231         </refsect2>
 232
 233         <refsect2 id="method-giofileenumerator--close-finish">
 234             <title>gio.FileEnumerator.close_finish</title>
 235
 236             <programlisting><methodsynopsis language="python">
 237                 <methodname>close_finish</methodname>
 238                 <methodparam><parameter role="keyword">result</parameter></methodparam>
 239             </methodsynopsis></programlisting>
 240
 241             <variablelist>
 242                 <varlistentry>
 243                   <term><parameter role="keyword">result</parameter>&nbsp;:</term>
 244                   <listitem><simpara>a GAsyncResult.
 245                   </simpara></listitem>
 246                 </varlistentry>
 247                 <varlistentry>
 248                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 249                     <listitem><simpara><literal>True</literal> if the close operation
 250                     has finished successfully.</simpara></listitem>
 251                 </varlistentry>
 252             </variablelist>
 253
 254             <para>
 255                 The <methodname>close_finish</methodname>() method finishes closing a file enumerator, started from
 256                 <methodname><link linkend="method-giofileenumerator--close-async">gio.FileEnumerator.close_async</link></methodname>().
 257             </para>
 258             <para>
 259                 If the file enumerator was already closed when
 260                 <methodname><link linkend="method-giofileenumerator--close-async">gio.FileEnumerator.close_async</link></methodname>()
 261                 was called, then this function will report gio.ERROR_CLOSED in error, and return <literal>False</literal>.
 262                 If the file enumerator had pending operation when the close operation was started, then this function will report
 263                 gio.ERROR_PENDING, and return <literal>False</literal>. If cancellable was not <literal>None</literal>, then the operation
 264                 may have been cancelled by triggering the cancellable object from another thread. If the operation was cancelled,
 265                 the error gio.ERROR_CANCELLED will be set, and <literal>False</literal> will be returned.
 266             </para>
 267         </refsect2>
 268
 269         <refsect2 id="method-giofileenumerator--get-container">
 270             <title>gio.FileEnumerator.get_container</title>
 271
 272             <programlisting><methodsynopsis language="python">
 273                 <methodname>get_container</methodname>
 274                 <methodparam></methodparam>
 275             </methodsynopsis></programlisting>
 276
 277             <variablelist>
 278                 <varlistentry>
 279                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 280                     <listitem><simpara>the <link linkend="class-giofile"><classname>gio.File</classname></link>
 281                     which is being enumerated. </simpara></listitem>
 282                 </varlistentry>
 283             </variablelist>
 284
 285             <para>
 286                 The <methodname>get_container</methodname>() method gets the
 287                 <link linkend="class-giofile"><classname>gio.File</classname></link>
 288                 container which is being enumerated.
 289             </para>
 290         </refsect2>
 291
 292         <refsect2 id="method-giofileenumerator--has-pending">
 293             <title>gio.FileEnumerator.has_pending</title>
 294
 295             <programlisting><methodsynopsis language="python">
 296                 <methodname>has_pending</methodname>
 297                 <methodparam></methodparam>
 298             </methodsynopsis></programlisting>
 299
 300             <variablelist>
 301             <varlistentry>
 302                 <term><emphasis>Returns</emphasis>&nbsp;:</term>
 303                 <listitem><simpara><literal>True</literal> if the enumerator has pending operations.</simpara></listitem>
 304             </varlistentry>
 305             </variablelist>
 306
 307             <para>
 308                 The <methodname>has_pending</methodname>() method checks if the file enumerator has pending operations.
 309             </para>
 310         </refsect2>
 311
 312         <refsect2 id="method-giofileenumerator--is-closed">
 313             <title>gio.FileEnumerator.is_closed</title>
 314
 315             <programlisting><methodsynopsis language="python">
 316                 <methodname>is_closed</methodname>
 317                 <methodparam></methodparam>
 318             </methodsynopsis></programlisting>
 319
 320             <variablelist>
 321                 <varlistentry>
 322                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 323                     <listitem><simpara><literal>True</literal> if the enumerator is closed.</simpara></listitem>
 324                 </varlistentry>
 325             </variablelist>
 326
 327             <para>
 328                 The <methodname>is_closed</methodname>() method checks if the file enumerator has been closed.
 329             </para>
 330         </refsect2>
 331
 332         <refsect2 id="method-giofileenumerator--next-file">
 333             <title>gio.FileEnumerator.next_file</title>
 334
 335             <programlisting><methodsynopsis language="python">
 336                 <methodname>next_file</methodname>
 337                 <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
 338             </methodsynopsis></programlisting>
 339
 340             <variablelist>
 341                 <varlistentry>
 342                   <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
 343                   <listitem><simpara>Optional
 344                   <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
 345                   object, <literal>None</literal> to ignore.
 346                   </simpara></listitem>
 347                 </varlistentry>
 348                 <varlistentry>
 349                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 350                     <listitem><simpara>A <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
 351                     or <literal>None</literal> on error or end of enumerator.
 352                     </simpara></listitem>
 353                 </varlistentry>
 354             </variablelist>
 355
 356             <para>
 357                 The <methodname>next_file</methodname>() method returns information for the next
 358                 file in the enumerated object. Will block until the information is available.
 359                 The <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
 360                 returned from this function will contain attributes that match the attribute string
 361                 that was passed when the GFileEnumerator was created.
 362             </para>
 363             <para>
 364                 On error, returns <literal>None</literal> and sets error to the error. If the enumerator
 365                 is at the end, <literal>None</literal> will be returned and error will be unset.
 366             </para>
 367         </refsect2>
 368
 369         <refsect2 id="method-giofileenumerator--next-files-async">
 370             <title>gio.FileEnumerator.next_files_async</title>
 371
 372             <programlisting><methodsynopsis language="python">
 373                 <methodname>next_files_async</methodname>
 374                 <methodparam><parameter role="keyword">num_files</parameter></methodparam>
 375                 <methodparam><parameter role="keyword">callback</parameter></methodparam>
 376                 <methodparam>
 377                     <parameter role="keyword">io_priority</parameter><initializer><literal>glib.PRIORITY_DEFAULT</literal></initializer>
 378                 </methodparam>
 379                 <methodparam>
 380                     <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer>
 381                 </methodparam>
 382                 <methodparam>
 383                     <parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer>
 384                 </methodparam>
 385             </methodsynopsis></programlisting>
 386
 387             <variablelist>
 388                 <varlistentry>
 389                   <term><parameter role="keyword">num_files</parameter>&nbsp;:</term>
 390                   <listitem><simpara>The number of file info objects to request.
 391                   </simpara></listitem>
 392                 </varlistentry>
 393                 <varlistentry>
 394                   <term><parameter role="keyword">callback</parameter>&nbsp;:</term>
 395                   <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied.
 396                   </simpara></listitem>
 397                 </varlistentry>
 398                 <varlistentry>
 399                   <term><parameter role="keyword">io_priority</parameter>&nbsp;:</term>
 400                   <listitem><simpara>The
 401                   <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> of the request.
 402                   </simpara></listitem>
 403                 </varlistentry>
 404                 <varlistentry>
 405                   <term><parameter role="keyword">cancellable</parameter>&nbsp;:</term>
 406                   <listitem><simpara>Optional
 407                   <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
 408                   object, <literal>None</literal> to ignore.
 409                   </simpara></listitem>
 410                 </varlistentry>
 411                 <varlistentry>
 412                   <term><parameter role="keyword">user_data</parameter>&nbsp;:</term>
 413                   <listitem><simpara>The data to pass to callback function.
 414                   </simpara></listitem>
 415                 </varlistentry>
 416             </variablelist>
 417
 418             <para>
 419                 The <methodname>next_files_async</methodname>() method requests information for a number
 420                 of files from the enumerator asynchronously. When all i/o for the operation is finished
 421                 the callback will be called with the requested information.
 422             </para>
 423             <para>
 424                 The callback can be called with less than num_files files in case of error or at the
 425                 end of the enumerator. In case of a partial error the callback will be called with any
 426                 succeeding items and no error, and on the next request the error will be reported. If a
 427                 request is cancelled the callback will be called with gio.ERROR_CANCELLED.
 428             </para>
 429             <para>
 430                 During an async request no other sync and async calls are allowed, and will result in gio.ERROR_PENDING errors.
 431             </para>
 432             <para>
 433                 Any outstanding i/o request with higher priority (lower numerical value) will be executed
 434                 before an outstanding request with lower priority. Default priority is glib.PRIORITY_DEFAULT.
 435             </para>
 436         </refsect2>
 437
 438         <refsect2 id="method-giofileenumerator--next-files-finish">
 439             <title>gio.FileEnumerator.next_files_finish</title>
 440
 441             <programlisting><methodsynopsis language="python">
 442                 <methodname>next_files_finish</methodname>
 443                 <methodparam><parameter role="keyword">result</parameter></methodparam>
 444             </methodsynopsis></programlisting>
 445
 446             <variablelist>
 447                 <varlistentry>
 448                   <term><parameter role="keyword">result</parameter>&nbsp;:</term>
 449                   <listitem><simpara>a GAsyncResult.
 450                   </simpara></listitem>
 451                 </varlistentry>
 452                 <varlistentry>
 453                     <term><emphasis>Returns</emphasis>&nbsp;:</term>
 454                     <listitem><simpara>A list of
 455                     <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>s.
 456                     </simpara></listitem>
 457                 </varlistentry>
 458             </variablelist>
 459
 460             <para>
 461                 The <methodname>next_files_finish</methodname>() method finishes the
 462                 asynchronous operation started with
 463                 <methodname><link linkend="method-giofileenumerator--next-files-async">gio.FileEnumerator.next_files_async</link></methodname>().
 464             </para>
 465         </refsect2>
 466
 467         <refsect2 id="method-giofileenumerator--set-pending">
 468             <title>gio.FileEnumerator.set_pending</title>
 469
 470             <programlisting><methodsynopsis language="python">
 471                 <methodname>set_pending</methodname>
 472                 <methodparam><parameter role="keyword">pending</parameter></methodparam>
 473             </methodsynopsis></programlisting>
 474
 475             <variablelist>
 476                 <varlistentry>
 477                   <term><parameter role="keyword">pending</parameter>&nbsp;:</term>
 478                   <listitem><simpara>A boolean value.
 479                   </simpara></listitem>
 480                 </varlistentry>
 481             </variablelist>
 482
 483             <para>
 484                 The <methodname>push_current</methodname>() method sets the file enumerator as having pending operations.
 485             </para>
 486         </refsect2>
 487     </refsect1>
 488 </refentry>