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"
32 struct _GFileEnumeratorPrivate {
33 /* TODO: Should be public for subclasses? */
37 GAsyncReadyCallback outstanding_callback;
38 GError *outstanding_error;
42 * SECTION:gfileenumerator
43 * @short_description: Enumerated Files Routines
46 * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
47 * returning a #GFileInfo structure for each file enumerated (e.g.
48 * g_file_enumerate_children() will return a #GFileEnumerator for each
49 * of the children within a directory).
51 * To get the next file's information from a #GFileEnumerator, use
52 * g_file_enumerator_next_file() or its asynchronous version,
53 * g_file_enumerator_next_files_async(). Note that the asynchronous
54 * version will return a list of #GFileInfo<!---->s, whereas the
55 * synchronous will only return the next file in the enumerator.
57 * The ordering of returned files is unspecified for non-Unix
58 * platforms; for more information, see g_dir_read_name(). On Unix,
59 * when operating on local files, returned files will be sorted by
60 * inode number. Effectively you can assume that the ordering of
61 * returned files will be stable between successive calls (and
62 * applications) assuming the directory is unchanged.
64 * If your application needs a specific ordering, such as by name or
65 * modification time, you will have to implement that in your
68 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
69 * its asynchronous version, g_file_enumerator_close_async(). Once
70 * a #GFileEnumerator is closed, no further actions may be performed
71 * on it, and it should be freed with g_object_unref().
75 G_DEFINE_TYPE_WITH_PRIVATE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT)
82 static void g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
85 GCancellable *cancellable,
86 GAsyncReadyCallback callback,
88 static GList * g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
91 static void g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
93 GCancellable *cancellable,
94 GAsyncReadyCallback callback,
96 static gboolean g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
101 g_file_enumerator_set_property (GObject *object,
106 GFileEnumerator *enumerator;
108 enumerator = G_FILE_ENUMERATOR (object);
110 switch (property_id) {
112 enumerator->priv->container = g_value_dup_object (value);
115 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
121 g_file_enumerator_dispose (GObject *object)
123 GFileEnumerator *enumerator;
125 enumerator = G_FILE_ENUMERATOR (object);
127 if (enumerator->priv->container) {
128 g_object_unref (enumerator->priv->container);
129 enumerator->priv->container = NULL;
132 G_OBJECT_CLASS (g_file_enumerator_parent_class)->dispose (object);
136 g_file_enumerator_finalize (GObject *object)
138 GFileEnumerator *enumerator;
140 enumerator = G_FILE_ENUMERATOR (object);
142 if (!enumerator->priv->closed)
143 g_file_enumerator_close (enumerator, NULL, NULL);
145 G_OBJECT_CLASS (g_file_enumerator_parent_class)->finalize (object);
149 g_file_enumerator_class_init (GFileEnumeratorClass *klass)
151 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
153 gobject_class->set_property = g_file_enumerator_set_property;
154 gobject_class->dispose = g_file_enumerator_dispose;
155 gobject_class->finalize = g_file_enumerator_finalize;
157 klass->next_files_async = g_file_enumerator_real_next_files_async;
158 klass->next_files_finish = g_file_enumerator_real_next_files_finish;
159 klass->close_async = g_file_enumerator_real_close_async;
160 klass->close_finish = g_file_enumerator_real_close_finish;
162 g_object_class_install_property
163 (gobject_class, PROP_CONTAINER,
164 g_param_spec_object ("container", P_("Container"),
165 P_("The container that is being enumerated"),
168 G_PARAM_CONSTRUCT_ONLY |
169 G_PARAM_STATIC_STRINGS));
173 g_file_enumerator_init (GFileEnumerator *enumerator)
175 enumerator->priv = g_file_enumerator_get_instance_private (enumerator);
179 * g_file_enumerator_next_file:
180 * @enumerator: a #GFileEnumerator.
181 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
182 * @error: location to store the error occurring, or %NULL to ignore
184 * Returns information for the next file in the enumerated object.
185 * Will block until the information is available. The #GFileInfo
186 * returned from this function will contain attributes that match the
187 * attribute string that was passed when the #GFileEnumerator was created.
189 * See the documentation of #GFileEnumerator for information about the
190 * order of returned files.
192 * On error, returns %NULL and sets @error to the error. If the
193 * enumerator is at the end, %NULL will be returned and @error will
196 * Return value: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
197 * Free the returned object with g_object_unref() when no longer needed.
200 g_file_enumerator_next_file (GFileEnumerator *enumerator,
201 GCancellable *cancellable,
204 GFileEnumeratorClass *class;
207 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
208 g_return_val_if_fail (enumerator != NULL, NULL);
210 if (enumerator->priv->closed)
212 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
213 _("Enumerator is closed"));
217 if (enumerator->priv->pending)
219 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
220 _("File enumerator has outstanding operation"));
224 if (enumerator->priv->outstanding_error)
226 g_propagate_error (error, enumerator->priv->outstanding_error);
227 enumerator->priv->outstanding_error = NULL;
231 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
234 g_cancellable_push_current (cancellable);
236 enumerator->priv->pending = TRUE;
237 info = (* class->next_file) (enumerator, cancellable, error);
238 enumerator->priv->pending = FALSE;
241 g_cancellable_pop_current (cancellable);
247 * g_file_enumerator_close:
248 * @enumerator: a #GFileEnumerator.
249 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
250 * @error: location to store the error occurring, or %NULL to ignore
252 * Releases all resources used by this enumerator, making the
253 * enumerator return %G_IO_ERROR_CLOSED on all calls.
255 * This will be automatically called when the last reference
256 * is dropped, but you might want to call this function to make
257 * sure resources are released as early as possible.
259 * Return value: #TRUE on success or #FALSE on error.
262 g_file_enumerator_close (GFileEnumerator *enumerator,
263 GCancellable *cancellable,
266 GFileEnumeratorClass *class;
268 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
269 g_return_val_if_fail (enumerator != NULL, FALSE);
271 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
273 if (enumerator->priv->closed)
276 if (enumerator->priv->pending)
278 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
279 _("File enumerator has outstanding operation"));
284 g_cancellable_push_current (cancellable);
286 enumerator->priv->pending = TRUE;
287 (* class->close_fn) (enumerator, cancellable, error);
288 enumerator->priv->pending = FALSE;
289 enumerator->priv->closed = TRUE;
292 g_cancellable_pop_current (cancellable);
298 next_async_callback_wrapper (GObject *source_object,
302 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
304 enumerator->priv->pending = FALSE;
305 if (enumerator->priv->outstanding_callback)
306 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
307 g_object_unref (enumerator);
311 * g_file_enumerator_next_files_async:
312 * @enumerator: a #GFileEnumerator.
313 * @num_files: the number of file info objects to request
314 * @io_priority: the <link linkend="io-priority">io priority</link>
316 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
317 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
318 * @user_data: (closure): the data to pass to callback function
320 * Request information for a number of files from the enumerator asynchronously.
321 * When all i/o for the operation is finished the @callback will be called with
322 * the requested information.
324 * See the documentation of #GFileEnumerator for information about the
325 * order of returned files.
327 * The callback can be called with less than @num_files files in case of error
328 * or at the end of the enumerator. In case of a partial error the callback will
329 * be called with any succeeding items and no error, and on the next request the
330 * error will be reported. If a request is cancelled the callback will be called
331 * with %G_IO_ERROR_CANCELLED.
333 * During an async request no other sync and async calls are allowed, and will
334 * result in %G_IO_ERROR_PENDING errors.
336 * Any outstanding i/o request with higher priority (lower numerical value) will
337 * be executed before an outstanding request with lower priority. Default
338 * priority is %G_PRIORITY_DEFAULT.
341 g_file_enumerator_next_files_async (GFileEnumerator *enumerator,
344 GCancellable *cancellable,
345 GAsyncReadyCallback callback,
348 GFileEnumeratorClass *class;
350 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
351 g_return_if_fail (enumerator != NULL);
352 g_return_if_fail (num_files >= 0);
358 task = g_task_new (enumerator, cancellable, callback, user_data);
359 g_task_set_source_tag (task, g_file_enumerator_next_files_async);
360 g_task_return_pointer (task, NULL, NULL);
361 g_object_unref (task);
365 if (enumerator->priv->closed)
367 g_task_report_new_error (enumerator, callback, user_data,
368 g_file_enumerator_next_files_async,
369 G_IO_ERROR, G_IO_ERROR_CLOSED,
370 _("File enumerator is already closed"));
374 if (enumerator->priv->pending)
376 g_task_report_new_error (enumerator, callback, user_data,
377 g_file_enumerator_next_files_async,
378 G_IO_ERROR, G_IO_ERROR_PENDING,
379 _("File enumerator has outstanding operation"));
383 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
385 enumerator->priv->pending = TRUE;
386 enumerator->priv->outstanding_callback = callback;
387 g_object_ref (enumerator);
388 (* class->next_files_async) (enumerator, num_files, io_priority, cancellable,
389 next_async_callback_wrapper, user_data);
393 * g_file_enumerator_next_files_finish:
394 * @enumerator: a #GFileEnumerator.
395 * @result: a #GAsyncResult.
396 * @error: a #GError location to store the error occurring, or %NULL to
399 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
401 * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with
402 * g_list_free() and unref the infos with g_object_unref() when you're
406 g_file_enumerator_next_files_finish (GFileEnumerator *enumerator,
407 GAsyncResult *result,
410 GFileEnumeratorClass *class;
412 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
413 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
415 if (g_async_result_legacy_propagate_error (result, error))
417 else if (g_async_result_is_tagged (result, g_file_enumerator_next_files_async))
418 return g_task_propagate_pointer (G_TASK (result), error);
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: (allow-none): optional #GCancellable object, %NULL to ignore.
444 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
445 * @user_data: (closure): 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_task_report_new_error (enumerator, callback, user_data,
468 g_file_enumerator_close_async,
469 G_IO_ERROR, G_IO_ERROR_CLOSED,
470 _("File enumerator is already closed"));
474 if (enumerator->priv->pending)
476 g_task_report_new_error (enumerator, callback, user_data,
477 g_file_enumerator_close_async,
478 G_IO_ERROR, G_IO_ERROR_PENDING,
479 _("File enumerator has outstanding operation"));
483 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
485 enumerator->priv->pending = TRUE;
486 enumerator->priv->outstanding_callback = callback;
487 g_object_ref (enumerator);
488 (* class->close_async) (enumerator, io_priority, cancellable,
489 close_async_callback_wrapper, user_data);
493 * g_file_enumerator_close_finish:
494 * @enumerator: a #GFileEnumerator.
495 * @result: a #GAsyncResult.
496 * @error: a #GError location to store the error occurring, or %NULL to
499 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
501 * If the file enumerator was already closed when g_file_enumerator_close_async()
502 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
503 * return %FALSE. If the file enumerator had pending operation when the close
504 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
505 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
506 * cancelled by triggering the cancellable object from another thread. If the operation
507 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
510 * Returns: %TRUE if the close operation has finished successfully.
513 g_file_enumerator_close_finish (GFileEnumerator *enumerator,
514 GAsyncResult *result,
517 GFileEnumeratorClass *class;
519 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
520 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
522 if (g_async_result_legacy_propagate_error (result, error))
524 else if (g_async_result_is_tagged (result, g_file_enumerator_close_async))
525 return g_task_propagate_boolean (G_TASK (result), error);
527 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
528 return class->close_finish (enumerator, result, error);
532 * g_file_enumerator_is_closed:
533 * @enumerator: a #GFileEnumerator.
535 * Checks if the file enumerator has been closed.
537 * Returns: %TRUE if the @enumerator is closed.
540 g_file_enumerator_is_closed (GFileEnumerator *enumerator)
542 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
544 return enumerator->priv->closed;
548 * g_file_enumerator_has_pending:
549 * @enumerator: a #GFileEnumerator.
551 * Checks if the file enumerator has pending operations.
553 * Returns: %TRUE if the @enumerator has pending operations.
556 g_file_enumerator_has_pending (GFileEnumerator *enumerator)
558 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
560 return enumerator->priv->pending;
564 * g_file_enumerator_set_pending:
565 * @enumerator: a #GFileEnumerator.
566 * @pending: a boolean value.
568 * Sets the file enumerator as having pending operations.
571 g_file_enumerator_set_pending (GFileEnumerator *enumerator,
574 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
576 enumerator->priv->pending = pending;
580 * g_file_enumerator_get_container:
581 * @enumerator: a #GFileEnumerator
583 * Get the #GFile container which is being enumerated.
585 * Returns: (transfer none): the #GFile which is being enumerated.
590 g_file_enumerator_get_container (GFileEnumerator *enumerator)
592 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
594 return enumerator->priv->container;
598 * g_file_enumerator_get_child:
599 * @enumerator: a #GFileEnumerator
600 * @info: a #GFileInfo gotten from g_file_enumerator_next_file()
601 * or the async equivalents.
603 * Return a new #GFile which refers to the file named by @info in the source
604 * directory of @enumerator. This function is primarily intended to be used
605 * inside loops with g_file_enumerator_next_file().
607 * This is a convenience method that's equivalent to:
609 * gchar *name = g_file_info_get_name (info);
610 * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
614 * Returns: (transfer full): a #GFile for the #GFileInfo passed it.
619 g_file_enumerator_get_child (GFileEnumerator *enumerator,
622 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
624 return g_file_get_child (enumerator->priv->container,
625 g_file_info_get_name (info));
629 next_async_op_free (GList *files)
631 g_list_free_full (files, g_object_unref);
635 next_files_thread (GTask *task,
636 gpointer source_object,
638 GCancellable *cancellable)
640 GFileEnumerator *enumerator = source_object;
641 int num_files = GPOINTER_TO_INT (task_data);
642 GFileEnumeratorClass *class;
644 GError *error = NULL;
648 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
650 for (i = 0; i < num_files; i++)
652 if (g_cancellable_set_error_if_cancelled (cancellable, &error))
655 info = class->next_file (enumerator, cancellable, &error);
659 /* If we get an error after first file, return that on next operation */
660 if (error != NULL && i > 0)
662 if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
663 g_error_free (error); /* Never propagate cancel errors to other call */
665 enumerator->priv->outstanding_error = error;
672 files = g_list_prepend (files, info);
676 g_task_return_error (task, error);
678 g_task_return_pointer (task, files, (GDestroyNotify)next_async_op_free);
682 g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
685 GCancellable *cancellable,
686 GAsyncReadyCallback callback,
691 task = g_task_new (enumerator, cancellable, callback, user_data);
692 g_task_set_task_data (task, GINT_TO_POINTER (num_files), NULL);
693 g_task_set_priority (task, io_priority);
695 g_task_run_in_thread (task, next_files_thread);
696 g_object_unref (task);
700 g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
701 GAsyncResult *result,
704 g_return_val_if_fail (g_task_is_valid (result, enumerator), NULL);
706 return g_task_propagate_pointer (G_TASK (result), error);
710 close_async_thread (GTask *task,
711 gpointer source_object,
713 GCancellable *cancellable)
715 GFileEnumerator *enumerator = source_object;
716 GFileEnumeratorClass *class;
717 GError *error = NULL;
720 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
721 result = class->close_fn (enumerator, cancellable, &error);
723 g_task_return_boolean (task, TRUE);
725 g_task_return_error (task, error);
729 g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
731 GCancellable *cancellable,
732 GAsyncReadyCallback callback,
737 task = g_task_new (enumerator, cancellable, callback, user_data);
738 g_task_set_priority (task, io_priority);
740 g_task_run_in_thread (task, close_async_thread);
741 g_object_unref (task);
745 g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
746 GAsyncResult *result,
749 g_return_val_if_fail (g_task_is_valid (result, enumerator), FALSE);
751 return g_task_propagate_boolean (G_TASK (result), error);