GioFileEnumeratoriterate

A version of g_file_enumerator_next_file() that’s easier to use correctly from C programs.

With g_file_enumerator_next_file(), the boolean return value signifies “end of iteration or error”, which requires allocation of a temporary GError to distinguish which one.

In contrast, with this function, a false return from g_file_enumerator_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 corresponding GFile as well as each GFileInfo.

To use this, G_FILE_ATTRIBUTE_STANDARD_NAME must have been listed in the attributes list used when creating the GFileEnumerator.

You must specify at least one of out_info or out_child.

The code pattern for correctly using g_file_enumerator_iterate() from C is:

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

Available since: 2.44