Method

GioFileEnumeratoriterate

since: 2.44

Declaration 

gboolean
g_file_enumerator_iterate (
  GFileEnumerator* direnum,
  GFileInfo** out_info,
  GFile** out_child,
  GCancellable* cancellable,
  GError** error
)

Description

This is a version of g_file_enumerator_next_file() that’s easier to use correctly from C programs. With g_file_enumerator_next_file(), 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 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 GFile as well.

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

Available since: 2.44

Parameters

out_info

Type: GFileInfo

Output location for the next GFileInfo, or NULL.

The argument will be set by the function.
The argument can be NULL.
The data is owned by the caller of the function.
out_child

Type: GFile

Output location for the next GFile, or NULL.

The argument will be set by the function.
The argument can be NULL.
The data is owned by the caller of the function.
cancellable

Type: GCancellable

A GCancellable.

The argument can be NULL.
The data is owned by the caller of the function.
error

Type: GError **

The return location for a recoverable error.

The argument can be NULL.
If the return location is not NULL, then you must initialize it to a NULL GError*.
The argument will left initialized to NULL by the method if there are no errors.
In case of error, the argument will be set to a newly allocated GError; the caller will take ownership of the data, and be responsible for freeing it.

Return value

Type: gboolean

No description available.