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.
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
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