iterate

A version of [method@Gio.

FileEnumerator.next_file] that’s easier to use correctly from C programs.

With [method@Gio.FileEnumerator.next_file], the boolean return value signifies “end of iteration or error”, which requires allocation of a temporary [type@GLib.Error] to distinguish which one.

In contrast, with this function, a false return from [method@Gio.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 this (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 corresponding [iface@Gio.File] as well as each [class@Gio.FileInfo].

To use this, [const@Gio.FILE_ATTRIBUTE_STANDARD_NAME] must have been listed in the attributes list used when creating the [ class@Gio.FileEnumerator].

You must specify at least one of out_info or out_child.

The code pattern for correctly using [method@Gio.FileEnumerator.iterate] from C is:

```c direnum = g_file_enumerate_children (file, ...); while (TRUE) { GFileInfo *info = NULL;

if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error)) goto out;

if (info == NULL) break;

// do stuff with "info"; do not unref it! ... }

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

Parameters:

this	an open file enumerator
out_info	return location for the next file info object, or `NULL`
out_child	return location for the next file object, or `NULL`
cancellable	optional cancellable object

Returns:

true on success or “end of iteration”; false on error