Virtual Method

GioFileEnumeratornext_files_async

Declaration

void
next_files_async (
  GFileEnumerator* enumerator,
  int num_files,
  int io_priority,
  GCancellable* cancellable,
  GAsyncReadyCallback callback,
  gpointer user_data
)

Description

Request information for a number of files from the enumerator asynchronously. When all I/O for the operation is finished the callback will be called with the requested information.

See the documentation of GFileEnumerator for information about the order of returned files.

Once the end of the enumerator is reached, or if an error occurs, the callback will be called with an empty list. In this case, the previous call to g_file_enumerator_next_files_async() will typically have returned fewer than num_files items.

If a request is cancelled the callback will be called with G_IO_ERROR_CANCELLED.

This leads to the following pseudo-code usage:

g_autoptr(GFile) dir = get_directory ();
g_autoptr(GFileEnumerator) enumerator = NULL;
g_autolist(GFileInfo) files = NULL;
g_autoptr(GError) local_error = NULL;

enumerator = yield g_file_enumerate_children_async (dir,
                                                    G_FILE_ATTRIBUTE_STANDARD_NAME ","
                                                    G_FILE_ATTRIBUTE_STANDARD_TYPE,
                                                    G_FILE_QUERY_INFO_NONE,
                                                    G_PRIORITY_DEFAULT,
                                                    cancellable,
                                                    …,
                                                    &local_error);
if (enumerator == NULL)
  g_error ("Error enumerating: %s", local_error->message);

// Loop until no files are returned, either because the end of the enumerator
// has been reached, or an error was returned.
do
  {
    files = yield g_file_enumerator_next_files_async (enumerator,
                                                      5,  // number of files to request
                                                      G_PRIORITY_DEFAULT,
                                                      cancellable,
                                                      …,
                                                      &local_error);

    // Process the returned files, but don’t assume that exactly 5 were returned.
    for (GList *l = files; l != NULL; l = l->next)
      {
        GFileInfo *info = l->data;
        handle_file_info (info);
      }
  }
while (files != NULL);

if (local_error != NULL &&
    !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
  g_error ("Error while enumerating: %s", local_error->message);

During an async request no other sync and async calls are allowed, and will result in G_IO_ERROR_PENDING errors.

Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is G_PRIORITY_DEFAULT.

Parameters

num_files

Type: int

The number of file info objects to request.

io_priority

Type: int

The I/O priority of the request.

cancellable

Type: GCancellable

Optional GCancellable object, NULL to ignore.

The argument can be NULL.

The data is owned by the caller of the function.

callback

Type: GAsyncReadyCallback

A GAsyncReadyCallback to call when the request is satisfied.

user_data

Type: gpointer

The data to pass to callback function.

The argument can be NULL.

The data is owned by the caller of the function.