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"
29 #include "gsimpleasyncresult.h"
36 * SECTION:gfileenumerator
37 * @short_description: Enumerated Files Routines
40 * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
41 * returning a #GFileInfo structure for each file enumerated (e.g.
42 * g_file_enumerate_children() will return a #GFileEnumerator for each
43 * of the children within a directory).
45 * To get the next file's information from a #GFileEnumerator, use
46 * g_file_enumerator_next_file() or its asynchronous version,
47 * g_file_enumerator_next_files_async(). Note that the asynchronous
48 * version will return a list of #GFileInfo<!---->s, whereas the
49 * synchronous will only return the next file in the enumerator.
51 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
52 * its asynchronous version, g_file_enumerator_close_async(). Once
53 * a #GFileEnumerator is closed, no further actions may be performed
54 * on it, and it should be freed with g_object_unref().
58 G_DEFINE_TYPE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT);
60 struct _GFileEnumeratorPrivate {
61 /* TODO: Should be public for subclasses? */
65 GAsyncReadyCallback outstanding_callback;
66 GError *outstanding_error;
74 static void g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
77 GCancellable *cancellable,
78 GAsyncReadyCallback callback,
80 static GList * g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
83 static void g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
85 GCancellable *cancellable,
86 GAsyncReadyCallback callback,
88 static gboolean g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
93 g_file_enumerator_set_property (GObject *object,
98 GFileEnumerator *enumerator;
100 enumerator = G_FILE_ENUMERATOR (object);
102 switch (property_id) {
104 enumerator->priv->container = g_value_dup_object (value);
107 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
113 g_file_enumerator_dispose (GObject *object)
115 GFileEnumerator *enumerator;
117 enumerator = G_FILE_ENUMERATOR (object);
119 if (enumerator->priv->container) {
120 g_object_unref (enumerator->priv->container);
121 enumerator->priv->container = NULL;
124 G_OBJECT_CLASS (g_file_enumerator_parent_class)->dispose (object);
128 g_file_enumerator_finalize (GObject *object)
130 GFileEnumerator *enumerator;
132 enumerator = G_FILE_ENUMERATOR (object);
134 if (!enumerator->priv->closed)
135 g_file_enumerator_close (enumerator, NULL, NULL);
137 G_OBJECT_CLASS (g_file_enumerator_parent_class)->finalize (object);
141 g_file_enumerator_class_init (GFileEnumeratorClass *klass)
143 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
145 g_type_class_add_private (klass, sizeof (GFileEnumeratorPrivate));
147 gobject_class->set_property = g_file_enumerator_set_property;
148 gobject_class->dispose = g_file_enumerator_dispose;
149 gobject_class->finalize = g_file_enumerator_finalize;
151 klass->next_files_async = g_file_enumerator_real_next_files_async;
152 klass->next_files_finish = g_file_enumerator_real_next_files_finish;
153 klass->close_async = g_file_enumerator_real_close_async;
154 klass->close_finish = g_file_enumerator_real_close_finish;
156 g_object_class_install_property
157 (gobject_class, PROP_CONTAINER,
158 g_param_spec_object ("container", P_("Container"),
159 P_("The container that is being enumerated"),
162 G_PARAM_CONSTRUCT_ONLY |
163 G_PARAM_STATIC_STRINGS));
167 g_file_enumerator_init (GFileEnumerator *enumerator)
169 enumerator->priv = G_TYPE_INSTANCE_GET_PRIVATE (enumerator,
170 G_TYPE_FILE_ENUMERATOR,
171 GFileEnumeratorPrivate);
175 * g_file_enumerator_next_file:
176 * @enumerator: a #GFileEnumerator.
177 * @cancellable: optional #GCancellable object, %NULL to ignore.
178 * @error: location to store the error occuring, or %NULL to ignore
180 * Returns information for the next file in the enumerated object.
181 * Will block until the information is available. The #GFileInfo
182 * returned from this function will contain attributes that match the
183 * attribute string that was passed when the #GFileEnumerator was created.
185 * On error, returns %NULL and sets @error to the error. If the
186 * enumerator is at the end, %NULL will be returned and @error will
189 * Return value: A #GFileInfo or %NULL on error or end of enumerator.
190 * Free the returned object with g_object_unref() when no longer needed.
193 g_file_enumerator_next_file (GFileEnumerator *enumerator,
194 GCancellable *cancellable,
197 GFileEnumeratorClass *class;
200 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
201 g_return_val_if_fail (enumerator != NULL, NULL);
203 if (enumerator->priv->closed)
205 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
206 _("Enumerator is closed"));
210 if (enumerator->priv->pending)
212 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
213 _("File enumerator has outstanding operation"));
217 if (enumerator->priv->outstanding_error)
219 g_propagate_error (error, enumerator->priv->outstanding_error);
220 enumerator->priv->outstanding_error = NULL;
224 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
227 g_cancellable_push_current (cancellable);
229 enumerator->priv->pending = TRUE;
230 info = (* class->next_file) (enumerator, cancellable, error);
231 enumerator->priv->pending = FALSE;
234 g_cancellable_pop_current (cancellable);
240 * g_file_enumerator_close:
241 * @enumerator: a #GFileEnumerator.
242 * @cancellable: optional #GCancellable object, %NULL to ignore.
243 * @error: location to store the error occuring, or %NULL to ignore
245 * Releases all resources used by this enumerator, making the
246 * enumerator return %G_IO_ERROR_CLOSED on all calls.
248 * This will be automatically called when the last reference
249 * is dropped, but you might want to call this function to make
250 * sure resources are released as early as possible.
252 * Return value: #TRUE on success or #FALSE on error.
255 g_file_enumerator_close (GFileEnumerator *enumerator,
256 GCancellable *cancellable,
259 GFileEnumeratorClass *class;
261 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
262 g_return_val_if_fail (enumerator != NULL, FALSE);
264 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
266 if (enumerator->priv->closed)
269 if (enumerator->priv->pending)
271 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
272 _("File enumerator has outstanding operation"));
277 g_cancellable_push_current (cancellable);
279 enumerator->priv->pending = TRUE;
280 (* class->close_fn) (enumerator, cancellable, error);
281 enumerator->priv->pending = FALSE;
282 enumerator->priv->closed = TRUE;
285 g_cancellable_pop_current (cancellable);
291 next_async_callback_wrapper (GObject *source_object,
295 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
297 enumerator->priv->pending = FALSE;
298 if (enumerator->priv->outstanding_callback)
299 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
300 g_object_unref (enumerator);
304 * g_file_enumerator_next_files_async:
305 * @enumerator: a #GFileEnumerator.
306 * @num_files: the number of file info objects to request
307 * @io_priority: the <link linkend="gioscheduler">io priority</link>
309 * @cancellable: optional #GCancellable object, %NULL to ignore.
310 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
311 * @user_data: the data to pass to callback function
313 * Request information for a number of files from the enumerator asynchronously.
314 * When all i/o for the operation is finished the @callback will be called with
315 * the requested information.
317 * The callback can be called with less than @num_files files in case of error
318 * or at the end of the enumerator. In case of a partial error the callback will
319 * be called with any succeeding items and no error, and on the next request the
320 * error will be reported. If a request is cancelled the callback will be called
321 * with %G_IO_ERROR_CANCELLED.
323 * During an async request no other sync and async calls are allowed, and will
324 * result in %G_IO_ERROR_PENDING errors.
326 * Any outstanding i/o request with higher priority (lower numerical value) will
327 * be executed before an outstanding request with lower priority. Default
328 * priority is %G_PRIORITY_DEFAULT.
331 g_file_enumerator_next_files_async (GFileEnumerator *enumerator,
334 GCancellable *cancellable,
335 GAsyncReadyCallback callback,
338 GFileEnumeratorClass *class;
339 GSimpleAsyncResult *simple;
341 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
342 g_return_if_fail (enumerator != NULL);
343 g_return_if_fail (num_files >= 0);
347 simple = g_simple_async_result_new (G_OBJECT (enumerator),
350 g_file_enumerator_next_files_async);
351 g_simple_async_result_complete_in_idle (simple);
352 g_object_unref (simple);
356 if (enumerator->priv->closed)
358 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
361 G_IO_ERROR, G_IO_ERROR_CLOSED,
362 _("File enumerator is already closed"));
366 if (enumerator->priv->pending)
368 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
371 G_IO_ERROR, G_IO_ERROR_PENDING,
372 _("File enumerator has outstanding operation"));
376 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
378 enumerator->priv->pending = TRUE;
379 enumerator->priv->outstanding_callback = callback;
380 g_object_ref (enumerator);
381 (* class->next_files_async) (enumerator, num_files, io_priority, cancellable,
382 next_async_callback_wrapper, user_data);
386 * g_file_enumerator_next_files_finish:
387 * @enumerator: a #GFileEnumerator.
388 * @result: a #GAsyncResult.
389 * @error: a #GError location to store the error occuring, or %NULL to
392 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
394 * Returns: a #GList of #GFileInfo<!---->s. You must free the list with
395 * g_list_free() and unref the infos with g_object_unref() when you're
399 g_file_enumerator_next_files_finish (GFileEnumerator *enumerator,
400 GAsyncResult *result,
403 GFileEnumeratorClass *class;
404 GSimpleAsyncResult *simple;
406 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
407 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
409 if (G_IS_SIMPLE_ASYNC_RESULT (result))
411 simple = G_SIMPLE_ASYNC_RESULT (result);
412 if (g_simple_async_result_propagate_error (simple, error))
415 /* Special case read of 0 files */
416 if (g_simple_async_result_get_source_tag (simple) == g_file_enumerator_next_files_async)
420 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
421 return class->next_files_finish (enumerator, result, error);
425 close_async_callback_wrapper (GObject *source_object,
429 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
431 enumerator->priv->pending = FALSE;
432 enumerator->priv->closed = TRUE;
433 if (enumerator->priv->outstanding_callback)
434 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
435 g_object_unref (enumerator);
439 * g_file_enumerator_close_async:
440 * @enumerator: a #GFileEnumerator.
441 * @io_priority: the <link linkend="io-priority">I/O priority</link>
443 * @cancellable: optional #GCancellable object, %NULL to ignore.
444 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
445 * @user_data: the data to pass to callback function
447 * Asynchronously closes the file enumerator.
449 * If @cancellable is not %NULL, then the operation can be cancelled by
450 * triggering the cancellable object from another thread. If the operation
451 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
452 * g_file_enumerator_close_finish().
455 g_file_enumerator_close_async (GFileEnumerator *enumerator,
457 GCancellable *cancellable,
458 GAsyncReadyCallback callback,
461 GFileEnumeratorClass *class;
463 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
465 if (enumerator->priv->closed)
467 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
470 G_IO_ERROR, G_IO_ERROR_CLOSED,
471 _("File enumerator is already closed"));
475 if (enumerator->priv->pending)
477 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
480 G_IO_ERROR, G_IO_ERROR_PENDING,
481 _("File enumerator has outstanding operation"));
485 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
487 enumerator->priv->pending = TRUE;
488 enumerator->priv->outstanding_callback = callback;
489 g_object_ref (enumerator);
490 (* class->close_async) (enumerator, io_priority, cancellable,
491 close_async_callback_wrapper, user_data);
495 * g_file_enumerator_close_finish:
496 * @enumerator: a #GFileEnumerator.
497 * @result: a #GAsyncResult.
498 * @error: a #GError location to store the error occuring, or %NULL to
501 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
503 * If the file enumerator was already closed when g_file_enumerator_close_async()
504 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
505 * return %FALSE. If the file enumerator had pending operation when the close
506 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
507 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
508 * cancelled by triggering the cancellable object from another thread. If the operation
509 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
512 * Returns: %TRUE if the close operation has finished successfully.
515 g_file_enumerator_close_finish (GFileEnumerator *enumerator,
516 GAsyncResult *result,
519 GSimpleAsyncResult *simple;
520 GFileEnumeratorClass *class;
522 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
523 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
525 if (G_IS_SIMPLE_ASYNC_RESULT (result))
527 simple = G_SIMPLE_ASYNC_RESULT (result);
528 if (g_simple_async_result_propagate_error (simple, error))
532 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
533 return class->close_finish (enumerator, result, error);
537 * g_file_enumerator_is_closed:
538 * @enumerator: a #GFileEnumerator.
540 * Checks if the file enumerator has been closed.
542 * Returns: %TRUE if the @enumerator is closed.
545 g_file_enumerator_is_closed (GFileEnumerator *enumerator)
547 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
549 return enumerator->priv->closed;
553 * g_file_enumerator_has_pending:
554 * @enumerator: a #GFileEnumerator.
556 * Checks if the file enumerator has pending operations.
558 * Returns: %TRUE if the @enumerator has pending operations.
561 g_file_enumerator_has_pending (GFileEnumerator *enumerator)
563 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
565 return enumerator->priv->pending;
569 * g_file_enumerator_set_pending:
570 * @enumerator: a #GFileEnumerator.
571 * @pending: a boolean value.
573 * Sets the file enumerator as having pending operations.
576 g_file_enumerator_set_pending (GFileEnumerator *enumerator,
579 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
581 enumerator->priv->pending = pending;
585 * g_file_enumerator_get_container:
586 * @enumerator: a #GFileEnumerator
588 * Get the #GFile container which is being enumerated.
590 * Returns: the #GFile which is being enumerated.
595 g_file_enumerator_get_container (GFileEnumerator *enumerator)
597 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
599 return enumerator->priv->container;
608 next_async_op_free (NextAsyncOp *op)
610 /* Free the list, if finish wasn't called */
611 g_list_foreach (op->files, (GFunc)g_object_unref, NULL);
612 g_list_free (op->files);
620 next_files_thread (GSimpleAsyncResult *res,
622 GCancellable *cancellable)
625 GFileEnumeratorClass *class;
626 GError *error = NULL;
628 GFileEnumerator *enumerator;
631 enumerator = G_FILE_ENUMERATOR (object);
632 op = g_simple_async_result_get_op_res_gpointer (res);
634 class = G_FILE_ENUMERATOR_GET_CLASS (object);
636 for (i = 0; i < op->num_files; i++)
638 if (g_cancellable_set_error_if_cancelled (cancellable, &error))
641 info = class->next_file (enumerator, cancellable, &error);
645 /* If we get an error after first file, return that on next operation */
646 if (error != NULL && i > 0)
648 if (error->domain == G_IO_ERROR &&
649 error->code == G_IO_ERROR_CANCELLED)
650 g_error_free (error); /* Never propagate cancel errors to other call */
652 enumerator->priv->outstanding_error = error;
659 op->files = g_list_prepend (op->files, info);
664 g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
667 GCancellable *cancellable,
668 GAsyncReadyCallback callback,
671 GSimpleAsyncResult *res;
674 op = g_new0 (NextAsyncOp, 1);
676 op->num_files = num_files;
679 res = g_simple_async_result_new (G_OBJECT (enumerator), callback, user_data, g_file_enumerator_real_next_files_async);
680 g_simple_async_result_set_op_res_gpointer (res, op, (GDestroyNotify) next_async_op_free);
682 g_simple_async_result_run_in_thread (res, next_files_thread, io_priority, cancellable);
683 g_object_unref (res);
687 g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
688 GAsyncResult *result,
691 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
695 g_warn_if_fail (g_simple_async_result_get_source_tag (simple) ==
696 g_file_enumerator_real_next_files_async);
698 op = g_simple_async_result_get_op_res_gpointer (simple);
706 close_async_thread (GSimpleAsyncResult *res,
708 GCancellable *cancellable)
710 GFileEnumeratorClass *class;
711 GError *error = NULL;
714 /* Auto handling of cancelation disabled, and ignore
715 cancellation, since we want to close things anyway, although
716 possibly in a quick-n-dirty way. At least we never want to leak
719 class = G_FILE_ENUMERATOR_GET_CLASS (object);
720 result = class->close_fn (G_FILE_ENUMERATOR (object), cancellable, &error);
723 g_simple_async_result_set_from_error (res, error);
724 g_error_free (error);
730 g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
732 GCancellable *cancellable,
733 GAsyncReadyCallback callback,
736 GSimpleAsyncResult *res;
738 res = g_simple_async_result_new (G_OBJECT (enumerator),
741 g_file_enumerator_real_close_async);
743 g_simple_async_result_set_handle_cancellation (res, FALSE);
745 g_simple_async_result_run_in_thread (res,
749 g_object_unref (res);
753 g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
754 GAsyncResult *result,
757 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
758 g_warn_if_fail (g_simple_async_result_get_source_tag (simple) ==
759 g_file_enumerator_real_close_async);
763 #define __G_FILE_ENUMERATOR_C__
764 #include "gioaliasdef.c"