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: (nullable) (transfer full): A #GFileInfo or %NULL on error
195 * or end of enumerator. Free the returned object with
196 * g_object_unref() when no longer needed.
199 g_file_enumerator_next_file (GFileEnumerator
*enumerator
,
200 GCancellable
*cancellable
,
203 GFileEnumeratorClass
*class;
206 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), NULL
);
207 g_return_val_if_fail (enumerator
!= NULL
, NULL
);
209 if (enumerator
->priv
->closed
)
211 g_set_error_literal (error
, G_IO_ERROR
, G_IO_ERROR_CLOSED
,
212 _("Enumerator is closed"));
216 if (enumerator
->priv
->pending
)
218 g_set_error_literal (error
, G_IO_ERROR
, G_IO_ERROR_PENDING
,
219 _("File enumerator has outstanding operation"));
223 if (enumerator
->priv
->outstanding_error
)
225 g_propagate_error (error
, enumerator
->priv
->outstanding_error
);
226 enumerator
->priv
->outstanding_error
= NULL
;
230 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
233 g_cancellable_push_current (cancellable
);
235 enumerator
->priv
->pending
= TRUE
;
236 info
= (* class->next_file
) (enumerator
, cancellable
, error
);
237 enumerator
->priv
->pending
= FALSE
;
240 g_cancellable_pop_current (cancellable
);
246 * g_file_enumerator_close:
247 * @enumerator: a #GFileEnumerator.
248 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
249 * @error: location to store the error occurring, or %NULL to ignore
251 * Releases all resources used by this enumerator, making the
252 * enumerator return %G_IO_ERROR_CLOSED on all calls.
254 * This will be automatically called when the last reference
255 * is dropped, but you might want to call this function to make
256 * sure resources are released as early as possible.
258 * Returns: #TRUE on success or #FALSE on error.
261 g_file_enumerator_close (GFileEnumerator
*enumerator
,
262 GCancellable
*cancellable
,
265 GFileEnumeratorClass
*class;
267 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), FALSE
);
268 g_return_val_if_fail (enumerator
!= NULL
, FALSE
);
270 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
272 if (enumerator
->priv
->closed
)
275 if (enumerator
->priv
->pending
)
277 g_set_error_literal (error
, G_IO_ERROR
, G_IO_ERROR_PENDING
,
278 _("File enumerator has outstanding operation"));
283 g_cancellable_push_current (cancellable
);
285 enumerator
->priv
->pending
= TRUE
;
286 (* class->close_fn
) (enumerator
, cancellable
, error
);
287 enumerator
->priv
->pending
= FALSE
;
288 enumerator
->priv
->closed
= TRUE
;
291 g_cancellable_pop_current (cancellable
);
297 next_async_callback_wrapper (GObject
*source_object
,
301 GFileEnumerator
*enumerator
= G_FILE_ENUMERATOR (source_object
);
303 enumerator
->priv
->pending
= FALSE
;
304 if (enumerator
->priv
->outstanding_callback
)
305 (*enumerator
->priv
->outstanding_callback
) (source_object
, res
, user_data
);
306 g_object_unref (enumerator
);
310 * g_file_enumerator_next_files_async:
311 * @enumerator: a #GFileEnumerator.
312 * @num_files: the number of file info objects to request
313 * @io_priority: the [I/O priority][io-priority] of the request
314 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
315 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
316 * @user_data: (closure): the data to pass to callback function
318 * Request information for a number of files from the enumerator asynchronously.
319 * When all i/o for the operation is finished the @callback will be called with
320 * the requested information.
322 * See the documentation of #GFileEnumerator for information about the
323 * order of returned files.
325 * The callback can be called with less than @num_files files in case of error
326 * or at the end of the enumerator. In case of a partial error the callback will
327 * be called with any succeeding items and no error, and on the next request the
328 * error will be reported. If a request is cancelled the callback will be called
329 * with %G_IO_ERROR_CANCELLED.
331 * During an async request no other sync and async calls are allowed, and will
332 * result in %G_IO_ERROR_PENDING errors.
334 * Any outstanding i/o request with higher priority (lower numerical value) will
335 * be executed before an outstanding request with lower priority. Default
336 * priority is %G_PRIORITY_DEFAULT.
339 g_file_enumerator_next_files_async (GFileEnumerator
*enumerator
,
342 GCancellable
*cancellable
,
343 GAsyncReadyCallback callback
,
346 GFileEnumeratorClass
*class;
348 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator
));
349 g_return_if_fail (enumerator
!= NULL
);
350 g_return_if_fail (num_files
>= 0);
356 task
= g_task_new (enumerator
, cancellable
, callback
, user_data
);
357 g_task_set_source_tag (task
, g_file_enumerator_next_files_async
);
358 g_task_return_pointer (task
, NULL
, NULL
);
359 g_object_unref (task
);
363 if (enumerator
->priv
->closed
)
365 g_task_report_new_error (enumerator
, callback
, user_data
,
366 g_file_enumerator_next_files_async
,
367 G_IO_ERROR
, G_IO_ERROR_CLOSED
,
368 _("File enumerator is already closed"));
372 if (enumerator
->priv
->pending
)
374 g_task_report_new_error (enumerator
, callback
, user_data
,
375 g_file_enumerator_next_files_async
,
376 G_IO_ERROR
, G_IO_ERROR_PENDING
,
377 _("File enumerator has outstanding operation"));
381 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
383 enumerator
->priv
->pending
= TRUE
;
384 enumerator
->priv
->outstanding_callback
= callback
;
385 g_object_ref (enumerator
);
386 (* class->next_files_async
) (enumerator
, num_files
, io_priority
, cancellable
,
387 next_async_callback_wrapper
, user_data
);
391 * g_file_enumerator_next_files_finish:
392 * @enumerator: a #GFileEnumerator.
393 * @result: a #GAsyncResult.
394 * @error: a #GError location to store the error occurring, or %NULL to
397 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
399 * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfos. You must free the list with
400 * g_list_free() and unref the infos with g_object_unref() when you're
404 g_file_enumerator_next_files_finish (GFileEnumerator
*enumerator
,
405 GAsyncResult
*result
,
408 GFileEnumeratorClass
*class;
410 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), NULL
);
411 g_return_val_if_fail (G_IS_ASYNC_RESULT (result
), NULL
);
413 if (g_async_result_legacy_propagate_error (result
, error
))
415 else if (g_async_result_is_tagged (result
, g_file_enumerator_next_files_async
))
416 return g_task_propagate_pointer (G_TASK (result
), error
);
418 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
419 return class->next_files_finish (enumerator
, result
, error
);
423 close_async_callback_wrapper (GObject
*source_object
,
427 GFileEnumerator
*enumerator
= G_FILE_ENUMERATOR (source_object
);
429 enumerator
->priv
->pending
= FALSE
;
430 enumerator
->priv
->closed
= TRUE
;
431 if (enumerator
->priv
->outstanding_callback
)
432 (*enumerator
->priv
->outstanding_callback
) (source_object
, res
, user_data
);
433 g_object_unref (enumerator
);
437 * g_file_enumerator_close_async:
438 * @enumerator: a #GFileEnumerator.
439 * @io_priority: the [I/O priority][io-priority] of the request
440 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
441 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
442 * @user_data: (closure): the data to pass to callback function
444 * Asynchronously closes the file enumerator.
446 * If @cancellable is not %NULL, then the operation can be cancelled by
447 * triggering the cancellable object from another thread. If the operation
448 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
449 * g_file_enumerator_close_finish().
452 g_file_enumerator_close_async (GFileEnumerator
*enumerator
,
454 GCancellable
*cancellable
,
455 GAsyncReadyCallback callback
,
458 GFileEnumeratorClass
*class;
460 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator
));
462 if (enumerator
->priv
->closed
)
464 g_task_report_new_error (enumerator
, callback
, user_data
,
465 g_file_enumerator_close_async
,
466 G_IO_ERROR
, G_IO_ERROR_CLOSED
,
467 _("File enumerator is already closed"));
471 if (enumerator
->priv
->pending
)
473 g_task_report_new_error (enumerator
, callback
, user_data
,
474 g_file_enumerator_close_async
,
475 G_IO_ERROR
, G_IO_ERROR_PENDING
,
476 _("File enumerator has outstanding operation"));
480 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
482 enumerator
->priv
->pending
= TRUE
;
483 enumerator
->priv
->outstanding_callback
= callback
;
484 g_object_ref (enumerator
);
485 (* class->close_async
) (enumerator
, io_priority
, cancellable
,
486 close_async_callback_wrapper
, user_data
);
490 * g_file_enumerator_close_finish:
491 * @enumerator: a #GFileEnumerator.
492 * @result: a #GAsyncResult.
493 * @error: a #GError location to store the error occurring, or %NULL to
496 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
498 * If the file enumerator was already closed when g_file_enumerator_close_async()
499 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
500 * return %FALSE. If the file enumerator had pending operation when the close
501 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
502 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
503 * cancelled by triggering the cancellable object from another thread. If the operation
504 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
507 * Returns: %TRUE if the close operation has finished successfully.
510 g_file_enumerator_close_finish (GFileEnumerator
*enumerator
,
511 GAsyncResult
*result
,
514 GFileEnumeratorClass
*class;
516 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), FALSE
);
517 g_return_val_if_fail (G_IS_ASYNC_RESULT (result
), FALSE
);
519 if (g_async_result_legacy_propagate_error (result
, error
))
521 else if (g_async_result_is_tagged (result
, g_file_enumerator_close_async
))
522 return g_task_propagate_boolean (G_TASK (result
), error
);
524 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
525 return class->close_finish (enumerator
, result
, error
);
529 * g_file_enumerator_is_closed:
530 * @enumerator: a #GFileEnumerator.
532 * Checks if the file enumerator has been closed.
534 * Returns: %TRUE if the @enumerator is closed.
537 g_file_enumerator_is_closed (GFileEnumerator
*enumerator
)
539 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), TRUE
);
541 return enumerator
->priv
->closed
;
545 * g_file_enumerator_has_pending:
546 * @enumerator: a #GFileEnumerator.
548 * Checks if the file enumerator has pending operations.
550 * Returns: %TRUE if the @enumerator has pending operations.
553 g_file_enumerator_has_pending (GFileEnumerator
*enumerator
)
555 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), TRUE
);
557 return enumerator
->priv
->pending
;
561 * g_file_enumerator_set_pending:
562 * @enumerator: a #GFileEnumerator.
563 * @pending: a boolean value.
565 * Sets the file enumerator as having pending operations.
568 g_file_enumerator_set_pending (GFileEnumerator
*enumerator
,
571 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator
));
573 enumerator
->priv
->pending
= pending
;
577 * g_file_enumerator_get_container:
578 * @enumerator: a #GFileEnumerator
580 * Get the #GFile container which is being enumerated.
582 * Returns: (transfer none): the #GFile which is being enumerated.
587 g_file_enumerator_get_container (GFileEnumerator
*enumerator
)
589 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), NULL
);
591 return enumerator
->priv
->container
;
595 * g_file_enumerator_get_child:
596 * @enumerator: a #GFileEnumerator
597 * @info: a #GFileInfo gotten from g_file_enumerator_next_file()
598 * or the async equivalents.
600 * Return a new #GFile which refers to the file named by @info in the source
601 * directory of @enumerator. This function is primarily intended to be used
602 * inside loops with g_file_enumerator_next_file().
604 * This is a convenience method that's equivalent to:
605 * |[<!-- language="C" -->
606 * gchar *name = g_file_info_get_name (info);
607 * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
611 * Returns: (transfer full): a #GFile for the #GFileInfo passed it.
616 g_file_enumerator_get_child (GFileEnumerator
*enumerator
,
619 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), NULL
);
621 return g_file_get_child (enumerator
->priv
->container
,
622 g_file_info_get_name (info
));
626 next_async_op_free (GList
*files
)
628 g_list_free_full (files
, g_object_unref
);
632 next_files_thread (GTask
*task
,
633 gpointer source_object
,
635 GCancellable
*cancellable
)
637 GFileEnumerator
*enumerator
= source_object
;
638 int num_files
= GPOINTER_TO_INT (task_data
);
639 GFileEnumeratorClass
*class;
641 GError
*error
= NULL
;
645 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
647 for (i
= 0; i
< num_files
; i
++)
649 if (g_cancellable_set_error_if_cancelled (cancellable
, &error
))
652 info
= class->next_file (enumerator
, cancellable
, &error
);
656 /* If we get an error after first file, return that on next operation */
657 if (error
!= NULL
&& i
> 0)
659 if (g_error_matches (error
, G_IO_ERROR
, G_IO_ERROR_CANCELLED
))
660 g_error_free (error
); /* Never propagate cancel errors to other call */
662 enumerator
->priv
->outstanding_error
= error
;
669 files
= g_list_prepend (files
, info
);
673 g_task_return_error (task
, error
);
675 g_task_return_pointer (task
, files
, (GDestroyNotify
)next_async_op_free
);
679 g_file_enumerator_real_next_files_async (GFileEnumerator
*enumerator
,
682 GCancellable
*cancellable
,
683 GAsyncReadyCallback callback
,
688 task
= g_task_new (enumerator
, cancellable
, callback
, user_data
);
689 g_task_set_task_data (task
, GINT_TO_POINTER (num_files
), NULL
);
690 g_task_set_priority (task
, io_priority
);
692 g_task_run_in_thread (task
, next_files_thread
);
693 g_object_unref (task
);
697 g_file_enumerator_real_next_files_finish (GFileEnumerator
*enumerator
,
698 GAsyncResult
*result
,
701 g_return_val_if_fail (g_task_is_valid (result
, enumerator
), NULL
);
703 return g_task_propagate_pointer (G_TASK (result
), error
);
707 close_async_thread (GTask
*task
,
708 gpointer source_object
,
710 GCancellable
*cancellable
)
712 GFileEnumerator
*enumerator
= source_object
;
713 GFileEnumeratorClass
*class;
714 GError
*error
= NULL
;
717 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
718 result
= class->close_fn (enumerator
, cancellable
, &error
);
720 g_task_return_boolean (task
, TRUE
);
722 g_task_return_error (task
, error
);
726 g_file_enumerator_real_close_async (GFileEnumerator
*enumerator
,
728 GCancellable
*cancellable
,
729 GAsyncReadyCallback callback
,
734 task
= g_task_new (enumerator
, cancellable
, callback
, user_data
);
735 g_task_set_priority (task
, io_priority
);
737 g_task_run_in_thread (task
, close_async_thread
);
738 g_object_unref (task
);
742 g_file_enumerator_real_close_finish (GFileEnumerator
*enumerator
,
743 GAsyncResult
*result
,
746 g_return_val_if_fail (g_task_is_valid (result
, enumerator
), FALSE
);
748 return g_task_propagate_boolean (G_TASK (result
), error
);