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"
25 #include "gioscheduler.h"
26 #include "gasynchelper.h"
27 #include "gsimpleasyncresult.h"
33 * SECTION:gfileenumerator
34 * @short_description: Enumerated Files Routines
37 * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
38 * returning a #GFileInfo structure for each file enumerated (e.g.
39 * g_file_enumerate_children() will return a #GFileEnumerator for each
40 * of the children within a directory).
42 * To get the next file's information from a #GFileEnumerator, use
43 * g_file_enumerator_next_file() or its asynchronous version,
44 * g_file_enumerator_next_file_async(). Note that the asynchronous
45 * version will return a list of #GFileInfo<!---->s, whereas the
46 * synchronous will only return the next file in the enumerator.
48 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
49 * its asynchronous version, g_file_enumerator_close_async(). Once
50 * a #GFileEnumerator is closed, no further actions may be performed
51 * on it, and it should be freed with g_object_unref().
55 G_DEFINE_TYPE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT);
57 struct _GFileEnumeratorPrivate {
58 /* TODO: Should be public for subclasses? */
62 GAsyncReadyCallback outstanding_callback;
63 GError *outstanding_error;
71 static void g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
74 GCancellable *cancellable,
75 GAsyncReadyCallback callback,
77 static GList * g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
80 static void g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
82 GCancellable *cancellable,
83 GAsyncReadyCallback callback,
85 static gboolean g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
90 g_file_enumerator_set_property (GObject *object,
95 GFileEnumerator *enumerator;
97 enumerator = G_FILE_ENUMERATOR (object);
99 switch (property_id) {
101 enumerator->priv->container = g_value_dup_object (value);
104 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
110 g_file_enumerator_dispose (GObject *object)
112 GFileEnumerator *enumerator;
114 enumerator = G_FILE_ENUMERATOR (object);
116 if (enumerator->priv->container) {
117 g_object_unref (enumerator->priv->container);
118 enumerator->priv->container = NULL;
121 G_OBJECT_CLASS (g_file_enumerator_parent_class)->dispose (object);
125 g_file_enumerator_finalize (GObject *object)
127 GFileEnumerator *enumerator;
129 enumerator = G_FILE_ENUMERATOR (object);
131 if (!enumerator->priv->closed)
132 g_file_enumerator_close (enumerator, NULL, NULL);
134 G_OBJECT_CLASS (g_file_enumerator_parent_class)->finalize (object);
138 g_file_enumerator_class_init (GFileEnumeratorClass *klass)
140 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
142 g_type_class_add_private (klass, sizeof (GFileEnumeratorPrivate));
144 gobject_class->set_property = g_file_enumerator_set_property;
145 gobject_class->dispose = g_file_enumerator_dispose;
146 gobject_class->finalize = g_file_enumerator_finalize;
148 klass->next_files_async = g_file_enumerator_real_next_files_async;
149 klass->next_files_finish = g_file_enumerator_real_next_files_finish;
150 klass->close_async = g_file_enumerator_real_close_async;
151 klass->close_finish = g_file_enumerator_real_close_finish;
153 g_object_class_install_property
154 (gobject_class, PROP_CONTAINER,
155 g_param_spec_object ("container", P_("Container"),
156 P_("The container that is being enumerated"),
159 G_PARAM_CONSTRUCT_ONLY |
160 G_PARAM_STATIC_STRINGS));
164 g_file_enumerator_init (GFileEnumerator *enumerator)
166 enumerator->priv = G_TYPE_INSTANCE_GET_PRIVATE (enumerator,
167 G_TYPE_FILE_ENUMERATOR,
168 GFileEnumeratorPrivate);
172 * g_file_enumerator_next_file:
173 * @enumerator: a #GFileEnumerator.
174 * @cancellable: optional #GCancellable object, %NULL to ignore.
175 * @error: location to store the error occuring, or %NULL to ignore
177 * Returns information for the next file in the enumerated object.
178 * Will block until the information is available. The #GFileInfo
179 * returned from this function will contain attributes that match the
180 * attribute string that was passed when the #GFileEnumerator was created.
182 * On error, returns %NULL and sets @error to the error. If the
183 * enumerator is at the end, %NULL will be returned and @error will
186 * Return value: A #GFileInfo or %NULL on error or end of enumerator
189 g_file_enumerator_next_file (GFileEnumerator *enumerator,
190 GCancellable *cancellable,
193 GFileEnumeratorClass *class;
196 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
197 g_return_val_if_fail (enumerator != NULL, NULL);
199 if (enumerator->priv->closed)
201 g_set_error (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
202 _("Enumerator is closed"));
206 if (enumerator->priv->pending)
208 g_set_error (error, G_IO_ERROR, G_IO_ERROR_PENDING,
209 _("File enumerator has outstanding operation"));
213 if (enumerator->priv->outstanding_error)
215 g_propagate_error (error, enumerator->priv->outstanding_error);
216 enumerator->priv->outstanding_error = NULL;
220 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
223 g_cancellable_push_current (cancellable);
225 enumerator->priv->pending = TRUE;
226 info = (* class->next_file) (enumerator, cancellable, error);
227 enumerator->priv->pending = FALSE;
230 g_cancellable_pop_current (cancellable);
236 * g_file_enumerator_close:
237 * @enumerator: a #GFileEnumerator.
238 * @cancellable: optional #GCancellable object, %NULL to ignore.
239 * @error: location to store the error occuring, or %NULL to ignore
241 * Releases all resources used by this enumerator, making the
242 * enumerator return %G_IO_ERROR_CLOSED on all calls.
244 * This will be automatically called when the last reference
245 * is dropped, but you might want to call this function to make
246 * sure resources are released as early as possible.
248 * Return value: #TRUE on success or #FALSE on error.
251 g_file_enumerator_close (GFileEnumerator *enumerator,
252 GCancellable *cancellable,
255 GFileEnumeratorClass *class;
257 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
258 g_return_val_if_fail (enumerator != NULL, FALSE);
260 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
262 if (enumerator->priv->closed)
265 if (enumerator->priv->pending)
267 g_set_error (error, G_IO_ERROR, G_IO_ERROR_PENDING,
268 _("File enumerator has outstanding operation"));
273 g_cancellable_push_current (cancellable);
275 enumerator->priv->pending = TRUE;
276 (* class->close_fn) (enumerator, cancellable, error);
277 enumerator->priv->pending = FALSE;
278 enumerator->priv->closed = TRUE;
281 g_cancellable_pop_current (cancellable);
287 next_async_callback_wrapper (GObject *source_object,
291 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
293 enumerator->priv->pending = FALSE;
294 if (enumerator->priv->outstanding_callback)
295 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
296 g_object_unref (enumerator);
300 * g_file_enumerator_next_files_async:
301 * @enumerator: a #GFileEnumerator.
302 * @num_files: the number of file info objects to request
303 * @io_priority: the <link linkend="gioscheduler">io priority</link>
305 * @cancellable: optional #GCancellable object, %NULL to ignore.
306 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
307 * @user_data: the data to pass to callback function
309 * Request information for a number of files from the enumerator asynchronously.
310 * When all i/o for the operation is finished the @callback will be called with
311 * the requested information.
313 * The callback can be called with less than @num_files files in case of error
314 * or at the end of the enumerator. In case of a partial error the callback will
315 * be called with any succeeding items and no error, and on the next request the
316 * error will be reported. If a request is cancelled the callback will be called
317 * with %G_IO_ERROR_CANCELLED.
319 * During an async request no other sync and async calls are allowed, and will
320 * result in %G_IO_ERROR_PENDING errors.
322 * Any outstanding i/o request with higher priority (lower numerical value) will
323 * be executed before an outstanding request with lower priority. Default
324 * priority is %G_PRIORITY_DEFAULT.
327 g_file_enumerator_next_files_async (GFileEnumerator *enumerator,
330 GCancellable *cancellable,
331 GAsyncReadyCallback callback,
334 GFileEnumeratorClass *class;
335 GSimpleAsyncResult *simple;
337 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
338 g_return_if_fail (enumerator != NULL);
339 g_return_if_fail (num_files >= 0);
343 simple = g_simple_async_result_new (G_OBJECT (enumerator),
346 g_file_enumerator_next_files_async);
347 g_simple_async_result_complete_in_idle (simple);
348 g_object_unref (simple);
352 if (enumerator->priv->closed)
354 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
357 G_IO_ERROR, G_IO_ERROR_CLOSED,
358 _("File enumerator is already closed"));
362 if (enumerator->priv->pending)
364 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
367 G_IO_ERROR, G_IO_ERROR_PENDING,
368 _("File enumerator has outstanding operation"));
372 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
374 enumerator->priv->pending = TRUE;
375 enumerator->priv->outstanding_callback = callback;
376 g_object_ref (enumerator);
377 (* class->next_files_async) (enumerator, num_files, io_priority, cancellable,
378 next_async_callback_wrapper, user_data);
382 * g_file_enumerator_next_files_finish:
383 * @enumerator: a #GFileEnumerator.
384 * @result: a #GAsyncResult.
385 * @error: a #GError location to store the error occuring, or %NULL to
388 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
390 * Returns: a #GList of #GFileInfo<!---->s. You must free the list with
391 * g_list_free() and unref the infos with g_object_unref when you're
395 g_file_enumerator_next_files_finish (GFileEnumerator *enumerator,
396 GAsyncResult *result,
399 GFileEnumeratorClass *class;
400 GSimpleAsyncResult *simple;
402 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
403 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
405 if (G_IS_SIMPLE_ASYNC_RESULT (result))
407 simple = G_SIMPLE_ASYNC_RESULT (result);
408 if (g_simple_async_result_propagate_error (simple, error))
411 /* Special case read of 0 files */
412 if (g_simple_async_result_get_source_tag (simple) == g_file_enumerator_next_files_async)
416 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
417 return class->next_files_finish (enumerator, result, error);
421 close_async_callback_wrapper (GObject *source_object,
425 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
427 enumerator->priv->pending = FALSE;
428 enumerator->priv->closed = TRUE;
429 if (enumerator->priv->outstanding_callback)
430 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
431 g_object_unref (enumerator);
435 * g_file_enumerator_close_async:
436 * @enumerator: a #GFileEnumerator.
437 * @io_priority: the <link linkend="io-priority">I/O priority</link>
439 * @cancellable: optional #GCancellable object, %NULL to ignore.
440 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
441 * @user_data: 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_simple_async_report_error_in_idle (G_OBJECT (enumerator),
466 G_IO_ERROR, G_IO_ERROR_CLOSED,
467 _("File enumerator is already closed"));
471 if (enumerator->priv->pending)
473 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
476 G_IO_ERROR, G_IO_ERROR_PENDING,
477 _("File enumerator has outstanding operation"));
481 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
483 enumerator->priv->pending = TRUE;
484 enumerator->priv->outstanding_callback = callback;
485 g_object_ref (enumerator);
486 (* class->close_async) (enumerator, io_priority, cancellable,
487 close_async_callback_wrapper, user_data);
491 * g_file_enumerator_close_finish:
492 * @enumerator: a #GFileEnumerator.
493 * @result: a #GAsyncResult.
494 * @error: a #GError location to store the error occuring, or %NULL to
497 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
499 * If the file enumerator was already closed when g_file_enumerator_close_async()
500 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
501 * return %FALSE. If the file enumerator had pending operation when the close
502 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
503 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
504 * cancelled by triggering the cancellable object from another thread. If the operation
505 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
508 * Returns: %TRUE if the close operation has finished successfully.
511 g_file_enumerator_close_finish (GFileEnumerator *enumerator,
512 GAsyncResult *result,
515 GSimpleAsyncResult *simple;
516 GFileEnumeratorClass *class;
518 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
519 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
521 if (G_IS_SIMPLE_ASYNC_RESULT (result))
523 simple = G_SIMPLE_ASYNC_RESULT (result);
524 if (g_simple_async_result_propagate_error (simple, error))
528 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
529 return class->close_finish (enumerator, result, error);
533 * g_file_enumerator_is_closed:
534 * @enumerator: a #GFileEnumerator.
536 * Checks if the file enumerator has been closed.
538 * Returns: %TRUE if the @enumerator is closed.
541 g_file_enumerator_is_closed (GFileEnumerator *enumerator)
543 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
545 return enumerator->priv->closed;
549 * g_file_enumerator_has_pending:
550 * @enumerator: a #GFileEnumerator.
552 * Checks if the file enumerator has pending operations.
554 * Returns: %TRUE if the @enumerator has pending operations.
557 g_file_enumerator_has_pending (GFileEnumerator *enumerator)
559 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
561 return enumerator->priv->pending;
565 * g_file_enumerator_set_pending:
566 * @enumerator: a #GFileEnumerator.
567 * @pending: a boolean value.
569 * Sets the file enumerator as having pending operations.
572 g_file_enumerator_set_pending (GFileEnumerator *enumerator,
575 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
577 enumerator->priv->pending = pending;
581 * g_file_enumerator_get_container:
582 * @enumerator: a #GFileEnumerator
584 * Get the #GFile container which is being enumerated.
586 * Returns: the #GFile which is being enumerated.
591 g_file_enumerator_get_container (GFileEnumerator *enumerator)
593 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
595 return enumerator->priv->container;
604 next_async_op_free (NextAsyncOp *op)
606 /* Free the list, if finish wasn't called */
607 g_list_foreach (op->files, (GFunc)g_object_unref, NULL);
608 g_list_free (op->files);
616 next_files_thread (GSimpleAsyncResult *res,
618 GCancellable *cancellable)
621 GFileEnumeratorClass *class;
622 GError *error = NULL;
624 GFileEnumerator *enumerator;
627 enumerator = G_FILE_ENUMERATOR (object);
628 op = g_simple_async_result_get_op_res_gpointer (res);
630 class = G_FILE_ENUMERATOR_GET_CLASS (object);
632 for (i = 0; i < op->num_files; i++)
634 if (g_cancellable_set_error_if_cancelled (cancellable, &error))
637 info = class->next_file (enumerator, cancellable, &error);
641 /* If we get an error after first file, return that on next operation */
642 if (error != NULL && i > 0)
644 if (error->domain == G_IO_ERROR &&
645 error->code == G_IO_ERROR_CANCELLED)
646 g_error_free (error); /* Never propagate cancel errors to other call */
648 enumerator->priv->outstanding_error = error;
655 op->files = g_list_prepend (op->files, info);
660 g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
663 GCancellable *cancellable,
664 GAsyncReadyCallback callback,
667 GSimpleAsyncResult *res;
670 op = g_new0 (NextAsyncOp, 1);
672 op->num_files = num_files;
675 res = g_simple_async_result_new (G_OBJECT (enumerator), callback, user_data, g_file_enumerator_real_next_files_async);
676 g_simple_async_result_set_op_res_gpointer (res, op, (GDestroyNotify) next_async_op_free);
678 g_simple_async_result_run_in_thread (res, next_files_thread, io_priority, cancellable);
679 g_object_unref (res);
683 g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
684 GAsyncResult *result,
687 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
691 g_warn_if_fail (g_simple_async_result_get_source_tag (simple) ==
692 g_file_enumerator_real_next_files_async);
694 op = g_simple_async_result_get_op_res_gpointer (simple);
702 close_async_thread (GSimpleAsyncResult *res,
704 GCancellable *cancellable)
706 GFileEnumeratorClass *class;
707 GError *error = NULL;
710 /* Auto handling of cancelation disabled, and ignore
711 cancellation, since we want to close things anyway, although
712 possibly in a quick-n-dirty way. At least we never want to leak
715 class = G_FILE_ENUMERATOR_GET_CLASS (object);
716 result = class->close_fn (G_FILE_ENUMERATOR (object), cancellable, &error);
719 g_simple_async_result_set_from_error (res, error);
720 g_error_free (error);
726 g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
728 GCancellable *cancellable,
729 GAsyncReadyCallback callback,
732 GSimpleAsyncResult *res;
734 res = g_simple_async_result_new (G_OBJECT (enumerator),
737 g_file_enumerator_real_close_async);
739 g_simple_async_result_set_handle_cancellation (res, FALSE);
741 g_simple_async_result_run_in_thread (res,
745 g_object_unref (res);
749 g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
750 GAsyncResult *result,
753 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
754 g_warn_if_fail (g_simple_async_result_get_source_tag (simple) ==
755 g_file_enumerator_real_close_async);
759 #define __G_FILE_ENUMERATOR_C__
760 #include "gioaliasdef.c"