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, write to the
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Author: Alexander Larsson <alexl@redhat.com>
24 #include "gfileenumerator.h"
26 #include "gioscheduler.h"
27 #include "gasyncresult.h"
28 #include "gasynchelper.h"
34 * SECTION:gfileenumerator
35 * @short_description: Enumerated Files Routines
38 * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
39 * returning a #GFileInfo structure for each file enumerated (e.g.
40 * g_file_enumerate_children() will return a #GFileEnumerator for each
41 * of the children within a directory).
43 * To get the next file's information from a #GFileEnumerator, use
44 * g_file_enumerator_next_file() or its asynchronous version,
45 * g_file_enumerator_next_files_async(). Note that the asynchronous
46 * version will return a list of #GFileInfo<!---->s, whereas the
47 * synchronous will only return the next file in the enumerator.
49 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
50 * its asynchronous version, g_file_enumerator_close_async(). Once
51 * a #GFileEnumerator is closed, no further actions may be performed
52 * on it, and it should be freed with g_object_unref().
56 G_DEFINE_TYPE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT);
58 struct _GFileEnumeratorPrivate {
59 /* TODO: Should be public for subclasses? */
63 GAsyncReadyCallback outstanding_callback;
64 GError *outstanding_error;
72 static void g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
75 GCancellable *cancellable,
76 GAsyncReadyCallback callback,
78 static GList * g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
81 static void g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
83 GCancellable *cancellable,
84 GAsyncReadyCallback callback,
86 static gboolean g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
91 g_file_enumerator_set_property (GObject *object,
96 GFileEnumerator *enumerator;
98 enumerator = G_FILE_ENUMERATOR (object);
100 switch (property_id) {
102 enumerator->priv->container = g_value_dup_object (value);
105 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
111 g_file_enumerator_dispose (GObject *object)
113 GFileEnumerator *enumerator;
115 enumerator = G_FILE_ENUMERATOR (object);
117 if (enumerator->priv->container) {
118 g_object_unref (enumerator->priv->container);
119 enumerator->priv->container = NULL;
122 G_OBJECT_CLASS (g_file_enumerator_parent_class)->dispose (object);
126 g_file_enumerator_finalize (GObject *object)
128 GFileEnumerator *enumerator;
130 enumerator = G_FILE_ENUMERATOR (object);
132 if (!enumerator->priv->closed)
133 g_file_enumerator_close (enumerator, NULL, NULL);
135 G_OBJECT_CLASS (g_file_enumerator_parent_class)->finalize (object);
139 g_file_enumerator_class_init (GFileEnumeratorClass *klass)
141 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
143 g_type_class_add_private (klass, sizeof (GFileEnumeratorPrivate));
145 gobject_class->set_property = g_file_enumerator_set_property;
146 gobject_class->dispose = g_file_enumerator_dispose;
147 gobject_class->finalize = g_file_enumerator_finalize;
149 klass->next_files_async = g_file_enumerator_real_next_files_async;
150 klass->next_files_finish = g_file_enumerator_real_next_files_finish;
151 klass->close_async = g_file_enumerator_real_close_async;
152 klass->close_finish = g_file_enumerator_real_close_finish;
154 g_object_class_install_property
155 (gobject_class, PROP_CONTAINER,
156 g_param_spec_object ("container", P_("Container"),
157 P_("The container that is being enumerated"),
160 G_PARAM_CONSTRUCT_ONLY |
161 G_PARAM_STATIC_STRINGS));
165 g_file_enumerator_init (GFileEnumerator *enumerator)
167 enumerator->priv = G_TYPE_INSTANCE_GET_PRIVATE (enumerator,
168 G_TYPE_FILE_ENUMERATOR,
169 GFileEnumeratorPrivate);
173 * g_file_enumerator_next_file:
174 * @enumerator: a #GFileEnumerator.
175 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
176 * @error: location to store the error occurring, or %NULL to ignore
178 * Returns information for the next file in the enumerated object.
179 * Will block until the information is available. The #GFileInfo
180 * returned from this function will contain attributes that match the
181 * attribute string that was passed when the #GFileEnumerator was created.
183 * On error, returns %NULL and sets @error to the error. If the
184 * enumerator is at the end, %NULL will be returned and @error will
187 * Return value: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
188 * Free the returned object with g_object_unref() when no longer needed.
191 g_file_enumerator_next_file (GFileEnumerator *enumerator,
192 GCancellable *cancellable,
195 GFileEnumeratorClass *class;
198 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
199 g_return_val_if_fail (enumerator != NULL, NULL);
201 if (enumerator->priv->closed)
203 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
204 _("Enumerator is closed"));
208 if (enumerator->priv->pending)
210 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
211 _("File enumerator has outstanding operation"));
215 if (enumerator->priv->outstanding_error)
217 g_propagate_error (error, enumerator->priv->outstanding_error);
218 enumerator->priv->outstanding_error = NULL;
222 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
225 g_cancellable_push_current (cancellable);
227 enumerator->priv->pending = TRUE;
228 info = (* class->next_file) (enumerator, cancellable, error);
229 enumerator->priv->pending = FALSE;
232 g_cancellable_pop_current (cancellable);
238 * g_file_enumerator_close:
239 * @enumerator: a #GFileEnumerator.
240 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
241 * @error: location to store the error occurring, or %NULL to ignore
243 * Releases all resources used by this enumerator, making the
244 * enumerator return %G_IO_ERROR_CLOSED on all calls.
246 * This will be automatically called when the last reference
247 * is dropped, but you might want to call this function to make
248 * sure resources are released as early as possible.
250 * Return value: #TRUE on success or #FALSE on error.
253 g_file_enumerator_close (GFileEnumerator *enumerator,
254 GCancellable *cancellable,
257 GFileEnumeratorClass *class;
259 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
260 g_return_val_if_fail (enumerator != NULL, FALSE);
262 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
264 if (enumerator->priv->closed)
267 if (enumerator->priv->pending)
269 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
270 _("File enumerator has outstanding operation"));
275 g_cancellable_push_current (cancellable);
277 enumerator->priv->pending = TRUE;
278 (* class->close_fn) (enumerator, cancellable, error);
279 enumerator->priv->pending = FALSE;
280 enumerator->priv->closed = TRUE;
283 g_cancellable_pop_current (cancellable);
289 next_async_callback_wrapper (GObject *source_object,
293 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
295 enumerator->priv->pending = FALSE;
296 if (enumerator->priv->outstanding_callback)
297 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
298 g_object_unref (enumerator);
302 * g_file_enumerator_next_files_async:
303 * @enumerator: a #GFileEnumerator.
304 * @num_files: the number of file info objects to request
305 * @io_priority: the <link linkend="io-priority">io priority</link>
307 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
308 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
309 * @user_data: (closure): the data to pass to callback function
311 * Request information for a number of files from the enumerator asynchronously.
312 * When all i/o for the operation is finished the @callback will be called with
313 * the requested information.
315 * The callback can be called with less than @num_files files in case of error
316 * or at the end of the enumerator. In case of a partial error the callback will
317 * be called with any succeeding items and no error, and on the next request the
318 * error will be reported. If a request is cancelled the callback will be called
319 * with %G_IO_ERROR_CANCELLED.
321 * During an async request no other sync and async calls are allowed, and will
322 * result in %G_IO_ERROR_PENDING errors.
324 * Any outstanding i/o request with higher priority (lower numerical value) will
325 * be executed before an outstanding request with lower priority. Default
326 * priority is %G_PRIORITY_DEFAULT.
329 g_file_enumerator_next_files_async (GFileEnumerator *enumerator,
332 GCancellable *cancellable,
333 GAsyncReadyCallback callback,
336 GFileEnumeratorClass *class;
338 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
339 g_return_if_fail (enumerator != NULL);
340 g_return_if_fail (num_files >= 0);
346 task = g_task_new (enumerator, cancellable, callback, user_data);
347 g_task_set_source_tag (task, g_file_enumerator_next_files_async);
348 g_task_return_pointer (task, NULL, NULL);
349 g_object_unref (task);
353 if (enumerator->priv->closed)
355 g_task_report_new_error (enumerator, callback, user_data,
356 g_file_enumerator_next_files_async,
357 G_IO_ERROR, G_IO_ERROR_CLOSED,
358 _("File enumerator is already closed"));
362 if (enumerator->priv->pending)
364 g_task_report_new_error (enumerator, callback, user_data,
365 g_file_enumerator_next_files_async,
366 G_IO_ERROR, G_IO_ERROR_PENDING,
367 _("File enumerator has outstanding operation"));
371 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
373 enumerator->priv->pending = TRUE;
374 enumerator->priv->outstanding_callback = callback;
375 g_object_ref (enumerator);
376 (* class->next_files_async) (enumerator, num_files, io_priority, cancellable,
377 next_async_callback_wrapper, user_data);
381 * g_file_enumerator_next_files_finish:
382 * @enumerator: a #GFileEnumerator.
383 * @result: a #GAsyncResult.
384 * @error: a #GError location to store the error occurring, or %NULL to
387 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
389 * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with
390 * g_list_free() and unref the infos with g_object_unref() when you're
394 g_file_enumerator_next_files_finish (GFileEnumerator *enumerator,
395 GAsyncResult *result,
398 GFileEnumeratorClass *class;
400 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
401 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
403 if (g_async_result_legacy_propagate_error (result, error))
405 else if (g_async_result_is_tagged (result, g_file_enumerator_next_files_async))
406 return g_task_propagate_pointer (G_TASK (result), error);
408 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
409 return class->next_files_finish (enumerator, result, error);
413 close_async_callback_wrapper (GObject *source_object,
417 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
419 enumerator->priv->pending = FALSE;
420 enumerator->priv->closed = TRUE;
421 if (enumerator->priv->outstanding_callback)
422 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
423 g_object_unref (enumerator);
427 * g_file_enumerator_close_async:
428 * @enumerator: a #GFileEnumerator.
429 * @io_priority: the <link linkend="io-priority">I/O priority</link>
431 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
432 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
433 * @user_data: (closure): the data to pass to callback function
435 * Asynchronously closes the file enumerator.
437 * If @cancellable is not %NULL, then the operation can be cancelled by
438 * triggering the cancellable object from another thread. If the operation
439 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
440 * g_file_enumerator_close_finish().
443 g_file_enumerator_close_async (GFileEnumerator *enumerator,
445 GCancellable *cancellable,
446 GAsyncReadyCallback callback,
449 GFileEnumeratorClass *class;
451 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
453 if (enumerator->priv->closed)
455 g_task_report_new_error (enumerator, callback, user_data,
456 g_file_enumerator_close_async,
457 G_IO_ERROR, G_IO_ERROR_CLOSED,
458 _("File enumerator is already closed"));
462 if (enumerator->priv->pending)
464 g_task_report_new_error (enumerator, callback, user_data,
465 g_file_enumerator_close_async,
466 G_IO_ERROR, G_IO_ERROR_PENDING,
467 _("File enumerator has outstanding operation"));
471 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
473 enumerator->priv->pending = TRUE;
474 enumerator->priv->outstanding_callback = callback;
475 g_object_ref (enumerator);
476 (* class->close_async) (enumerator, io_priority, cancellable,
477 close_async_callback_wrapper, user_data);
481 * g_file_enumerator_close_finish:
482 * @enumerator: a #GFileEnumerator.
483 * @result: a #GAsyncResult.
484 * @error: a #GError location to store the error occurring, or %NULL to
487 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
489 * If the file enumerator was already closed when g_file_enumerator_close_async()
490 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
491 * return %FALSE. If the file enumerator had pending operation when the close
492 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
493 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
494 * cancelled by triggering the cancellable object from another thread. If the operation
495 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
498 * Returns: %TRUE if the close operation has finished successfully.
501 g_file_enumerator_close_finish (GFileEnumerator *enumerator,
502 GAsyncResult *result,
505 GFileEnumeratorClass *class;
507 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
508 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
510 if (g_async_result_legacy_propagate_error (result, error))
512 else if (g_async_result_is_tagged (result, g_file_enumerator_close_async))
513 return g_task_propagate_boolean (G_TASK (result), error);
515 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
516 return class->close_finish (enumerator, result, error);
520 * g_file_enumerator_is_closed:
521 * @enumerator: a #GFileEnumerator.
523 * Checks if the file enumerator has been closed.
525 * Returns: %TRUE if the @enumerator is closed.
528 g_file_enumerator_is_closed (GFileEnumerator *enumerator)
530 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
532 return enumerator->priv->closed;
536 * g_file_enumerator_has_pending:
537 * @enumerator: a #GFileEnumerator.
539 * Checks if the file enumerator has pending operations.
541 * Returns: %TRUE if the @enumerator has pending operations.
544 g_file_enumerator_has_pending (GFileEnumerator *enumerator)
546 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
548 return enumerator->priv->pending;
552 * g_file_enumerator_set_pending:
553 * @enumerator: a #GFileEnumerator.
554 * @pending: a boolean value.
556 * Sets the file enumerator as having pending operations.
559 g_file_enumerator_set_pending (GFileEnumerator *enumerator,
562 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
564 enumerator->priv->pending = pending;
568 * g_file_enumerator_get_container:
569 * @enumerator: a #GFileEnumerator
571 * Get the #GFile container which is being enumerated.
573 * Returns: (transfer none): the #GFile which is being enumerated.
578 g_file_enumerator_get_container (GFileEnumerator *enumerator)
580 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
582 return enumerator->priv->container;
586 * g_file_enumerator_get_child:
587 * @enumerator: a #GFileEnumerator
588 * @info: a #GFileInfo gotten from g_file_enumerator_next_file()
589 * or the async equivalents.
591 * Return a new #GFile which refers to the file named by @info in the source
592 * directory of @enumerator. This function is primarily intended to be used
593 * inside loops with g_file_enumerator_next_file().
595 * This is a convenience method that's equivalent to:
597 * gchar *name = g_file_info_get_name (info);
598 * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
602 * Returns: (transfer full): a #GFile for the #GFileInfo passed it.
607 g_file_enumerator_get_child (GFileEnumerator *enumerator,
610 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
612 return g_file_get_child (enumerator->priv->container,
613 g_file_info_get_name (info));
617 next_async_op_free (GList *files)
619 g_list_free_full (files, g_object_unref);
623 next_files_thread (GTask *task,
624 gpointer source_object,
626 GCancellable *cancellable)
628 GFileEnumerator *enumerator = source_object;
629 int num_files = GPOINTER_TO_INT (task_data);
630 GFileEnumeratorClass *class;
632 GError *error = NULL;
636 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
638 for (i = 0; i < num_files; i++)
640 if (g_cancellable_set_error_if_cancelled (cancellable, &error))
643 info = class->next_file (enumerator, cancellable, &error);
647 /* If we get an error after first file, return that on next operation */
648 if (error != NULL && i > 0)
650 if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
651 g_error_free (error); /* Never propagate cancel errors to other call */
653 enumerator->priv->outstanding_error = error;
660 files = g_list_prepend (files, info);
664 g_task_return_error (task, error);
666 g_task_return_pointer (task, files, (GDestroyNotify)next_async_op_free);
670 g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
673 GCancellable *cancellable,
674 GAsyncReadyCallback callback,
679 task = g_task_new (enumerator, cancellable, callback, user_data);
680 g_task_set_task_data (task, GINT_TO_POINTER (num_files), NULL);
681 g_task_set_priority (task, io_priority);
683 g_task_run_in_thread (task, next_files_thread);
684 g_object_unref (task);
688 g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
689 GAsyncResult *result,
692 g_return_val_if_fail (g_task_is_valid (result, enumerator), NULL);
694 return g_task_propagate_pointer (G_TASK (result), error);
698 close_async_thread (GTask *task,
699 gpointer source_object,
701 GCancellable *cancellable)
703 GFileEnumerator *enumerator = source_object;
704 GFileEnumeratorClass *class;
705 GError *error = NULL;
708 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
709 result = class->close_fn (enumerator, cancellable, &error);
711 g_task_return_boolean (task, TRUE);
713 g_task_return_error (task, error);
717 g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
719 GCancellable *cancellable,
720 GAsyncReadyCallback callback,
725 task = g_task_new (enumerator, cancellable, callback, user_data);
726 g_task_set_priority (task, io_priority);
728 g_task_run_in_thread (task, close_async_thread);
729 g_object_unref (task);
733 g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
734 GAsyncResult *result,
737 g_return_val_if_fail (g_task_is_valid (result, enumerator), FALSE);
739 return g_task_propagate_boolean (G_TASK (result), error);