FileEnumerator.iterate

This is a version of [gio.file_enumerator.FileEnumerator.nextFile] that's easier to use correctly from C programs. With [gio.file_enumerator.FileEnumerator.nextFile], the gboolean return value signifies "end of iteration or error", which requires allocation of a temporary #GError.

In contrast, with this function, a false return from [gio.file_enumerator.FileEnumerator.iterate] always means "error". End of iteration is signaled by out_info or out_child being null.

Another crucial difference is that the references for out_info and out_child are owned by direnum (they are cached as hidden properties). You must not unref them in your own code. This makes memory management significantly easier for C code in combination with loops.

Finally, this function optionally allows retrieving a #GFile as well.

You must specify at least one of out_info or out_child.

The code pattern for correctly using [gio.file_enumerator.FileEnumerator.iterate] from C is:

direnum = g_file_enumerate_children (file, ...);
while (TRUE)
 {
   GFileInfo *info;
   if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
     goto out;
   if (!info)
     break;
   ... do stuff with "info"; do not unref it! ...
 }

out:
 g_object_unref (direnum); // Note: frees the last info