1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2006-2007 Red Hat, Inc.
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 * Author: Alexander Larsson <alexl@redhat.com>
22 #include "gfileenumerator.h"
24 #include "gioscheduler.h"
25 #include "gasyncresult.h"
26 #include "gasynchelper.h"
30 struct _GFileEnumeratorPrivate {
31 /* TODO: Should be public for subclasses? */
35 GAsyncReadyCallback outstanding_callback;
36 GError *outstanding_error;
40 * SECTION:gfileenumerator
41 * @short_description: Enumerated Files Routines
44 * #GFileEnumerator allows you to operate on a set of #GFiles,
45 * returning a #GFileInfo structure for each file enumerated (e.g.
46 * g_file_enumerate_children() will return a #GFileEnumerator for each
47 * of the children within a directory).
49 * To get the next file's information from a #GFileEnumerator, use
50 * g_file_enumerator_next_file() or its asynchronous version,
51 * g_file_enumerator_next_files_async(). Note that the asynchronous
52 * version will return a list of #GFileInfos, whereas the
53 * synchronous will only return the next file in the enumerator.
55 * The ordering of returned files is unspecified for non-Unix
56 * platforms; for more information, see g_dir_read_name(). On Unix,
57 * when operating on local files, returned files will be sorted by
58 * inode number. Effectively you can assume that the ordering of
59 * returned files will be stable between successive calls (and
60 * applications) assuming the directory is unchanged.
62 * If your application needs a specific ordering, such as by name or
63 * modification time, you will have to implement that in your
66 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
67 * its asynchronous version, g_file_enumerator_close_async(). Once
68 * a #GFileEnumerator is closed, no further actions may be performed
69 * on it, and it should be freed with g_object_unref().
73 G_DEFINE_TYPE_WITH_PRIVATE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT)
80 static void g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
83 GCancellable *cancellable,
84 GAsyncReadyCallback callback,
86 static GList * g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
89 static void g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
91 GCancellable *cancellable,
92 GAsyncReadyCallback callback,
94 static gboolean g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
99 g_file_enumerator_set_property (GObject *object,
104 GFileEnumerator *enumerator;
106 enumerator = G_FILE_ENUMERATOR (object);
108 switch (property_id) {
110 enumerator->priv->container = g_value_dup_object (value);
113 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
119 g_file_enumerator_dispose (GObject *object)
121 GFileEnumerator *enumerator;
123 enumerator = G_FILE_ENUMERATOR (object);
125 if (enumerator->priv->container) {
126 g_object_unref (enumerator->priv->container);
127 enumerator->priv->container = NULL;
130 G_OBJECT_CLASS (g_file_enumerator_parent_class)->dispose (object);
134 g_file_enumerator_finalize (GObject *object)
136 GFileEnumerator *enumerator;
138 enumerator = G_FILE_ENUMERATOR (object);
140 if (!enumerator->priv->closed)
141 g_file_enumerator_close (enumerator, NULL, NULL);
143 G_OBJECT_CLASS (g_file_enumerator_parent_class)->finalize (object);
147 g_file_enumerator_class_init (GFileEnumeratorClass *klass)
149 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
151 gobject_class->set_property = g_file_enumerator_set_property;
152 gobject_class->dispose = g_file_enumerator_dispose;
153 gobject_class->finalize = g_file_enumerator_finalize;
155 klass->next_files_async = g_file_enumerator_real_next_files_async;
156 klass->next_files_finish = g_file_enumerator_real_next_files_finish;
157 klass->close_async = g_file_enumerator_real_close_async;
158 klass->close_finish = g_file_enumerator_real_close_finish;
160 g_object_class_install_property
161 (gobject_class, PROP_CONTAINER,
162 g_param_spec_object ("container", P_("Container"),
163 P_("The container that is being enumerated"),
166 G_PARAM_CONSTRUCT_ONLY |
167 G_PARAM_STATIC_STRINGS));
171 g_file_enumerator_init (GFileEnumerator *enumerator)
173 enumerator->priv = g_file_enumerator_get_instance_private (enumerator);
177 * g_file_enumerator_next_file:
178 * @enumerator: a #GFileEnumerator.
179 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
180 * @error: location to store the error occurring, or %NULL to ignore
182 * Returns information for the next file in the enumerated object.
183 * Will block until the information is available. The #GFileInfo
184 * returned from this function will contain attributes that match the
185 * attribute string that was passed when the #GFileEnumerator was created.
187 * See the documentation of #GFileEnumerator for information about the
188 * order of returned files.
190 * On error, returns %NULL and sets @error to the error. If the
191 * enumerator is at the end, %NULL will be returned and @error will
194 * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
195 * Free the returned object with g_object_unref() when no longer needed.
198 g_file_enumerator_next_file (GFileEnumerator *enumerator,
199 GCancellable *cancellable,
202 GFileEnumeratorClass *class;
205 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
206 g_return_val_if_fail (enumerator != NULL, NULL);
208 if (enumerator->priv->closed)
210 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
211 _("Enumerator is closed"));
215 if (enumerator->priv->pending)
217 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
218 _("File enumerator has outstanding operation"));
222 if (enumerator->priv->outstanding_error)
224 g_propagate_error (error, enumerator->priv->outstanding_error);
225 enumerator->priv->outstanding_error = NULL;
229 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
232 g_cancellable_push_current (cancellable);
234 enumerator->priv->pending = TRUE;
235 info = (* class->next_file) (enumerator, cancellable, error);
236 enumerator->priv->pending = FALSE;
239 g_cancellable_pop_current (cancellable);
245 * g_file_enumerator_close:
246 * @enumerator: a #GFileEnumerator.
247 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
248 * @error: location to store the error occurring, or %NULL to ignore
250 * Releases all resources used by this enumerator, making the
251 * enumerator return %G_IO_ERROR_CLOSED on all calls.
253 * This will be automatically called when the last reference
254 * is dropped, but you might want to call this function to make
255 * sure resources are released as early as possible.
257 * Returns: #TRUE on success or #FALSE on error.
260 g_file_enumerator_close (GFileEnumerator *enumerator,
261 GCancellable *cancellable,
264 GFileEnumeratorClass *class;
266 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
267 g_return_val_if_fail (enumerator != NULL, FALSE);
269 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
271 if (enumerator->priv->closed)
274 if (enumerator->priv->pending)
276 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
277 _("File enumerator has outstanding operation"));
282 g_cancellable_push_current (cancellable);
284 enumerator->priv->pending = TRUE;
285 (* class->close_fn) (enumerator, cancellable, error);
286 enumerator->priv->pending = FALSE;
287 enumerator->priv->closed = TRUE;
290 g_cancellable_pop_current (cancellable);
296 next_async_callback_wrapper (GObject *source_object,
300 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
302 enumerator->priv->pending = FALSE;
303 if (enumerator->priv->outstanding_callback)
304 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
305 g_object_unref (enumerator);
309 * g_file_enumerator_next_files_async:
310 * @enumerator: a #GFileEnumerator.
311 * @num_files: the number of file info objects to request
312 * @io_priority: the [I/O priority][io-priority] of the request
313 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
314 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
315 * @user_data: (closure): the data to pass to callback function
317 * Request information for a number of files from the enumerator asynchronously.
318 * When all i/o for the operation is finished the @callback will be called with
319 * the requested information.
321 * See the documentation of #GFileEnumerator for information about the
322 * order of returned files.
324 * The callback can be called with less than @num_files files in case of error
325 * or at the end of the enumerator. In case of a partial error the callback will
326 * be called with any succeeding items and no error, and on the next request the
327 * error will be reported. If a request is cancelled the callback will be called
328 * with %G_IO_ERROR_CANCELLED.
330 * During an async request no other sync and async calls are allowed, and will
331 * result in %G_IO_ERROR_PENDING errors.
333 * Any outstanding i/o request with higher priority (lower numerical value) will
334 * be executed before an outstanding request with lower priority. Default
335 * priority is %G_PRIORITY_DEFAULT.
338 g_file_enumerator_next_files_async (GFileEnumerator *enumerator,
341 GCancellable *cancellable,
342 GAsyncReadyCallback callback,
345 GFileEnumeratorClass *class;
347 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
348 g_return_if_fail (enumerator != NULL);
349 g_return_if_fail (num_files >= 0);
355 task = g_task_new (enumerator, cancellable, callback, user_data);
356 g_task_set_source_tag (task, g_file_enumerator_next_files_async);
357 g_task_return_pointer (task, NULL, NULL);
358 g_object_unref (task);
362 if (enumerator->priv->closed)
364 g_task_report_new_error (enumerator, callback, user_data,
365 g_file_enumerator_next_files_async,
366 G_IO_ERROR, G_IO_ERROR_CLOSED,
367 _("File enumerator is already closed"));
371 if (enumerator->priv->pending)
373 g_task_report_new_error (enumerator, callback, user_data,
374 g_file_enumerator_next_files_async,
375 G_IO_ERROR, G_IO_ERROR_PENDING,
376 _("File enumerator has outstanding operation"));
380 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
382 enumerator->priv->pending = TRUE;
383 enumerator->priv->outstanding_callback = callback;
384 g_object_ref (enumerator);
385 (* class->next_files_async) (enumerator, num_files, io_priority, cancellable,
386 next_async_callback_wrapper, user_data);
390 * g_file_enumerator_next_files_finish:
391 * @enumerator: a #GFileEnumerator.
392 * @result: a #GAsyncResult.
393 * @error: a #GError location to store the error occurring, or %NULL to
396 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
398 * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with
399 * g_list_free() and unref the infos with g_object_unref() when you're
403 g_file_enumerator_next_files_finish (GFileEnumerator *enumerator,
404 GAsyncResult *result,
407 GFileEnumeratorClass *class;
409 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
410 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
412 if (g_async_result_legacy_propagate_error (result, error))
414 else if (g_async_result_is_tagged (result, g_file_enumerator_next_files_async))
415 return g_task_propagate_pointer (G_TASK (result), error);
417 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
418 return class->next_files_finish (enumerator, result, error);
422 close_async_callback_wrapper (GObject *source_object,
426 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
428 enumerator->priv->pending = FALSE;
429 enumerator->priv->closed = TRUE;
430 if (enumerator->priv->outstanding_callback)
431 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
432 g_object_unref (enumerator);
436 * g_file_enumerator_close_async:
437 * @enumerator: a #GFileEnumerator.
438 * @io_priority: the [I/O priority][io-priority] of the request
439 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
440 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
441 * @user_data: (closure): the data to pass to callback function
443 * Asynchronously closes the file enumerator.
445 * If @cancellable is not %NULL, then the operation can be cancelled by
446 * triggering the cancellable object from another thread. If the operation
447 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
448 * g_file_enumerator_close_finish().
451 g_file_enumerator_close_async (GFileEnumerator *enumerator,
453 GCancellable *cancellable,
454 GAsyncReadyCallback callback,
457 GFileEnumeratorClass *class;
459 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
461 if (enumerator->priv->closed)
463 g_task_report_new_error (enumerator, callback, user_data,
464 g_file_enumerator_close_async,
465 G_IO_ERROR, G_IO_ERROR_CLOSED,
466 _("File enumerator is already closed"));
470 if (enumerator->priv->pending)
472 g_task_report_new_error (enumerator, callback, user_data,
473 g_file_enumerator_close_async,
474 G_IO_ERROR, G_IO_ERROR_PENDING,
475 _("File enumerator has outstanding operation"));
479 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
481 enumerator->priv->pending = TRUE;
482 enumerator->priv->outstanding_callback = callback;
483 g_object_ref (enumerator);
484 (* class->close_async) (enumerator, io_priority, cancellable,
485 close_async_callback_wrapper, user_data);
489 * g_file_enumerator_close_finish:
490 * @enumerator: a #GFileEnumerator.
491 * @result: a #GAsyncResult.
492 * @error: a #GError location to store the error occurring, or %NULL to
495 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
497 * If the file enumerator was already closed when g_file_enumerator_close_async()
498 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
499 * return %FALSE. If the file enumerator had pending operation when the close
500 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
501 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
502 * cancelled by triggering the cancellable object from another thread. If the operation
503 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
506 * Returns: %TRUE if the close operation has finished successfully.
509 g_file_enumerator_close_finish (GFileEnumerator *enumerator,
510 GAsyncResult *result,
513 GFileEnumeratorClass *class;
515 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
516 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
518 if (g_async_result_legacy_propagate_error (result, error))
520 else if (g_async_result_is_tagged (result, g_file_enumerator_close_async))
521 return g_task_propagate_boolean (G_TASK (result), error);
523 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
524 return class->close_finish (enumerator, result, error);
528 * g_file_enumerator_is_closed:
529 * @enumerator: a #GFileEnumerator.
531 * Checks if the file enumerator has been closed.
533 * Returns: %TRUE if the @enumerator is closed.
536 g_file_enumerator_is_closed (GFileEnumerator *enumerator)
538 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
540 return enumerator->priv->closed;
544 * g_file_enumerator_has_pending:
545 * @enumerator: a #GFileEnumerator.
547 * Checks if the file enumerator has pending operations.
549 * Returns: %TRUE if the @enumerator has pending operations.
552 g_file_enumerator_has_pending (GFileEnumerator *enumerator)
554 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
556 return enumerator->priv->pending;
560 * g_file_enumerator_set_pending:
561 * @enumerator: a #GFileEnumerator.
562 * @pending: a boolean value.
564 * Sets the file enumerator as having pending operations.
567 g_file_enumerator_set_pending (GFileEnumerator *enumerator,
570 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
572 enumerator->priv->pending = pending;
576 * g_file_enumerator_get_container:
577 * @enumerator: a #GFileEnumerator
579 * Get the #GFile container which is being enumerated.
581 * Returns: (transfer none): the #GFile which is being enumerated.
586 g_file_enumerator_get_container (GFileEnumerator *enumerator)
588 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
590 return enumerator->priv->container;
594 * g_file_enumerator_get_child:
595 * @enumerator: a #GFileEnumerator
596 * @info: a #GFileInfo gotten from g_file_enumerator_next_file()
597 * or the async equivalents.
599 * Return a new #GFile which refers to the file named by @info in the source
600 * directory of @enumerator. This function is primarily intended to be used
601 * inside loops with g_file_enumerator_next_file().
603 * This is a convenience method that's equivalent to:
604 * |[<!-- language="C" -->
605 * gchar *name = g_file_info_get_name (info);
606 * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
610 * Returns: (transfer full): a #GFile for the #GFileInfo passed it.
615 g_file_enumerator_get_child (GFileEnumerator *enumerator,
618 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
620 return g_file_get_child (enumerator->priv->container,
621 g_file_info_get_name (info));
625 next_async_op_free (GList *files)
627 g_list_free_full (files, g_object_unref);
631 next_files_thread (GTask *task,
632 gpointer source_object,
634 GCancellable *cancellable)
636 GFileEnumerator *enumerator = source_object;
637 int num_files = GPOINTER_TO_INT (task_data);
638 GFileEnumeratorClass *class;
640 GError *error = NULL;
644 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
646 for (i = 0; i < num_files; i++)
648 if (g_cancellable_set_error_if_cancelled (cancellable, &error))
651 info = class->next_file (enumerator, cancellable, &error);
655 /* If we get an error after first file, return that on next operation */
656 if (error != NULL && i > 0)
658 if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
659 g_error_free (error); /* Never propagate cancel errors to other call */
661 enumerator->priv->outstanding_error = error;
668 files = g_list_prepend (files, info);
672 g_task_return_error (task, error);
674 g_task_return_pointer (task, files, (GDestroyNotify)next_async_op_free);
678 g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
681 GCancellable *cancellable,
682 GAsyncReadyCallback callback,
687 task = g_task_new (enumerator, cancellable, callback, user_data);
688 g_task_set_task_data (task, GINT_TO_POINTER (num_files), NULL);
689 g_task_set_priority (task, io_priority);
691 g_task_run_in_thread (task, next_files_thread);
692 g_object_unref (task);
696 g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
697 GAsyncResult *result,
700 g_return_val_if_fail (g_task_is_valid (result, enumerator), NULL);
702 return g_task_propagate_pointer (G_TASK (result), error);
706 close_async_thread (GTask *task,
707 gpointer source_object,
709 GCancellable *cancellable)
711 GFileEnumerator *enumerator = source_object;
712 GFileEnumeratorClass *class;
713 GError *error = NULL;
716 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
717 result = class->close_fn (enumerator, cancellable, &error);
719 g_task_return_boolean (task, TRUE);
721 g_task_return_error (task, error);
725 g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
727 GCancellable *cancellable,
728 GAsyncReadyCallback callback,
733 task = g_task_new (enumerator, cancellable, callback, user_data);
734 g_task_set_priority (task, io_priority);
736 g_task_run_in_thread (task, close_async_thread);
737 g_object_unref (task);
741 g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
742 GAsyncResult *result,
745 g_return_val_if_fail (g_task_is_valid (result, enumerator), FALSE);
747 return g_task_propagate_boolean (G_TASK (result), error);