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"
35 * SECTION:gfileenumerator
36 * @short_description: Enumerated Files Routines
39 * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
40 * returning a #GFileInfo structure for each file enumerated (e.g.
41 * g_file_enumerate_children() will return a #GFileEnumerator for each
42 * of the children within a directory).
44 * To get the next file's information from a #GFileEnumerator, use
45 * g_file_enumerator_next_file() or its asynchronous version,
46 * g_file_enumerator_next_files_async(). Note that the asynchronous
47 * version will return a list of #GFileInfo<!---->s, whereas the
48 * synchronous will only return the next file in the enumerator.
50 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
51 * its asynchronous version, g_file_enumerator_close_async(). Once
52 * a #GFileEnumerator is closed, no further actions may be performed
53 * on it, and it should be freed with g_object_unref().
57 G_DEFINE_TYPE (GFileEnumerator
, g_file_enumerator
, G_TYPE_OBJECT
);
59 struct _GFileEnumeratorPrivate
{
60 /* TODO: Should be public for subclasses? */
64 GAsyncReadyCallback outstanding_callback
;
65 GError
*outstanding_error
;
73 static void g_file_enumerator_real_next_files_async (GFileEnumerator
*enumerator
,
76 GCancellable
*cancellable
,
77 GAsyncReadyCallback callback
,
79 static GList
* g_file_enumerator_real_next_files_finish (GFileEnumerator
*enumerator
,
82 static void g_file_enumerator_real_close_async (GFileEnumerator
*enumerator
,
84 GCancellable
*cancellable
,
85 GAsyncReadyCallback callback
,
87 static gboolean
g_file_enumerator_real_close_finish (GFileEnumerator
*enumerator
,
92 g_file_enumerator_set_property (GObject
*object
,
97 GFileEnumerator
*enumerator
;
99 enumerator
= G_FILE_ENUMERATOR (object
);
101 switch (property_id
) {
103 enumerator
->priv
->container
= g_value_dup_object (value
);
106 G_OBJECT_WARN_INVALID_PROPERTY_ID (object
, property_id
, pspec
);
112 g_file_enumerator_dispose (GObject
*object
)
114 GFileEnumerator
*enumerator
;
116 enumerator
= G_FILE_ENUMERATOR (object
);
118 if (enumerator
->priv
->container
) {
119 g_object_unref (enumerator
->priv
->container
);
120 enumerator
->priv
->container
= NULL
;
123 G_OBJECT_CLASS (g_file_enumerator_parent_class
)->dispose (object
);
127 g_file_enumerator_finalize (GObject
*object
)
129 GFileEnumerator
*enumerator
;
131 enumerator
= G_FILE_ENUMERATOR (object
);
133 if (!enumerator
->priv
->closed
)
134 g_file_enumerator_close (enumerator
, NULL
, NULL
);
136 G_OBJECT_CLASS (g_file_enumerator_parent_class
)->finalize (object
);
140 g_file_enumerator_class_init (GFileEnumeratorClass
*klass
)
142 GObjectClass
*gobject_class
= G_OBJECT_CLASS (klass
);
144 g_type_class_add_private (klass
, sizeof (GFileEnumeratorPrivate
));
146 gobject_class
->set_property
= g_file_enumerator_set_property
;
147 gobject_class
->dispose
= g_file_enumerator_dispose
;
148 gobject_class
->finalize
= g_file_enumerator_finalize
;
150 klass
->next_files_async
= g_file_enumerator_real_next_files_async
;
151 klass
->next_files_finish
= g_file_enumerator_real_next_files_finish
;
152 klass
->close_async
= g_file_enumerator_real_close_async
;
153 klass
->close_finish
= g_file_enumerator_real_close_finish
;
155 g_object_class_install_property
156 (gobject_class
, PROP_CONTAINER
,
157 g_param_spec_object ("container", P_("Container"),
158 P_("The container that is being enumerated"),
161 G_PARAM_CONSTRUCT_ONLY
|
162 G_PARAM_STATIC_STRINGS
));
166 g_file_enumerator_init (GFileEnumerator
*enumerator
)
168 enumerator
->priv
= G_TYPE_INSTANCE_GET_PRIVATE (enumerator
,
169 G_TYPE_FILE_ENUMERATOR
,
170 GFileEnumeratorPrivate
);
174 * g_file_enumerator_next_file:
175 * @enumerator: a #GFileEnumerator.
176 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
177 * @error: location to store the error occurring, or %NULL to ignore
179 * Returns information for the next file in the enumerated object.
180 * Will block until the information is available. The #GFileInfo
181 * returned from this function will contain attributes that match the
182 * attribute string that was passed when the #GFileEnumerator was created.
184 * On error, returns %NULL and sets @error to the error. If the
185 * enumerator is at the end, %NULL will be returned and @error will
188 * Return value: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
189 * Free the returned object with g_object_unref() when no longer needed.
192 g_file_enumerator_next_file (GFileEnumerator
*enumerator
,
193 GCancellable
*cancellable
,
196 GFileEnumeratorClass
*class;
199 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), NULL
);
200 g_return_val_if_fail (enumerator
!= NULL
, NULL
);
202 if (enumerator
->priv
->closed
)
204 g_set_error_literal (error
, G_IO_ERROR
, G_IO_ERROR_CLOSED
,
205 _("Enumerator is closed"));
209 if (enumerator
->priv
->pending
)
211 g_set_error_literal (error
, G_IO_ERROR
, G_IO_ERROR_PENDING
,
212 _("File enumerator has outstanding operation"));
216 if (enumerator
->priv
->outstanding_error
)
218 g_propagate_error (error
, enumerator
->priv
->outstanding_error
);
219 enumerator
->priv
->outstanding_error
= NULL
;
223 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
226 g_cancellable_push_current (cancellable
);
228 enumerator
->priv
->pending
= TRUE
;
229 info
= (* class->next_file
) (enumerator
, cancellable
, error
);
230 enumerator
->priv
->pending
= FALSE
;
233 g_cancellable_pop_current (cancellable
);
239 * g_file_enumerator_close:
240 * @enumerator: a #GFileEnumerator.
241 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
242 * @error: location to store the error occurring, or %NULL to ignore
244 * Releases all resources used by this enumerator, making the
245 * enumerator return %G_IO_ERROR_CLOSED on all calls.
247 * This will be automatically called when the last reference
248 * is dropped, but you might want to call this function to make
249 * sure resources are released as early as possible.
251 * Return value: #TRUE on success or #FALSE on error.
254 g_file_enumerator_close (GFileEnumerator
*enumerator
,
255 GCancellable
*cancellable
,
258 GFileEnumeratorClass
*class;
260 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), FALSE
);
261 g_return_val_if_fail (enumerator
!= NULL
, FALSE
);
263 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
265 if (enumerator
->priv
->closed
)
268 if (enumerator
->priv
->pending
)
270 g_set_error_literal (error
, G_IO_ERROR
, G_IO_ERROR_PENDING
,
271 _("File enumerator has outstanding operation"));
276 g_cancellable_push_current (cancellable
);
278 enumerator
->priv
->pending
= TRUE
;
279 (* class->close_fn
) (enumerator
, cancellable
, error
);
280 enumerator
->priv
->pending
= FALSE
;
281 enumerator
->priv
->closed
= TRUE
;
284 g_cancellable_pop_current (cancellable
);
290 next_async_callback_wrapper (GObject
*source_object
,
294 GFileEnumerator
*enumerator
= G_FILE_ENUMERATOR (source_object
);
296 enumerator
->priv
->pending
= FALSE
;
297 if (enumerator
->priv
->outstanding_callback
)
298 (*enumerator
->priv
->outstanding_callback
) (source_object
, res
, user_data
);
299 g_object_unref (enumerator
);
303 * g_file_enumerator_next_files_async:
304 * @enumerator: a #GFileEnumerator.
305 * @num_files: the number of file info objects to request
306 * @io_priority: the <link linkend="gioscheduler">io priority</link>
308 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
309 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
310 * @user_data: (closure): the data to pass to callback function
312 * Request information for a number of files from the enumerator asynchronously.
313 * When all i/o for the operation is finished the @callback will be called with
314 * the requested information.
316 * The callback can be called with less than @num_files files in case of error
317 * or at the end of the enumerator. In case of a partial error the callback will
318 * be called with any succeeding items and no error, and on the next request the
319 * error will be reported. If a request is cancelled the callback will be called
320 * with %G_IO_ERROR_CANCELLED.
322 * During an async request no other sync and async calls are allowed, and will
323 * result in %G_IO_ERROR_PENDING errors.
325 * Any outstanding i/o request with higher priority (lower numerical value) will
326 * be executed before an outstanding request with lower priority. Default
327 * priority is %G_PRIORITY_DEFAULT.
330 g_file_enumerator_next_files_async (GFileEnumerator
*enumerator
,
333 GCancellable
*cancellable
,
334 GAsyncReadyCallback callback
,
337 GFileEnumeratorClass
*class;
338 GSimpleAsyncResult
*simple
;
340 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator
));
341 g_return_if_fail (enumerator
!= NULL
);
342 g_return_if_fail (num_files
>= 0);
346 simple
= g_simple_async_result_new (G_OBJECT (enumerator
),
349 g_file_enumerator_next_files_async
);
350 g_simple_async_result_complete_in_idle (simple
);
351 g_object_unref (simple
);
355 if (enumerator
->priv
->closed
)
357 g_simple_async_report_error_in_idle (G_OBJECT (enumerator
),
360 G_IO_ERROR
, G_IO_ERROR_CLOSED
,
361 _("File enumerator is already closed"));
365 if (enumerator
->priv
->pending
)
367 g_simple_async_report_error_in_idle (G_OBJECT (enumerator
),
370 G_IO_ERROR
, G_IO_ERROR_PENDING
,
371 _("File enumerator has outstanding operation"));
375 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
377 enumerator
->priv
->pending
= TRUE
;
378 enumerator
->priv
->outstanding_callback
= callback
;
379 g_object_ref (enumerator
);
380 (* class->next_files_async
) (enumerator
, num_files
, io_priority
, cancellable
,
381 next_async_callback_wrapper
, user_data
);
385 * g_file_enumerator_next_files_finish:
386 * @enumerator: a #GFileEnumerator.
387 * @result: a #GAsyncResult.
388 * @error: a #GError location to store the error occurring, or %NULL to
391 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
393 * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with
394 * g_list_free() and unref the infos with g_object_unref() when you're
398 g_file_enumerator_next_files_finish (GFileEnumerator
*enumerator
,
399 GAsyncResult
*result
,
402 GFileEnumeratorClass
*class;
403 GSimpleAsyncResult
*simple
;
405 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), NULL
);
406 g_return_val_if_fail (G_IS_ASYNC_RESULT (result
), NULL
);
408 if (G_IS_SIMPLE_ASYNC_RESULT (result
))
410 simple
= G_SIMPLE_ASYNC_RESULT (result
);
411 if (g_simple_async_result_propagate_error (simple
, error
))
414 /* Special case read of 0 files */
415 if (g_simple_async_result_get_source_tag (simple
) == g_file_enumerator_next_files_async
)
419 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
420 return class->next_files_finish (enumerator
, result
, error
);
424 close_async_callback_wrapper (GObject
*source_object
,
428 GFileEnumerator
*enumerator
= G_FILE_ENUMERATOR (source_object
);
430 enumerator
->priv
->pending
= FALSE
;
431 enumerator
->priv
->closed
= TRUE
;
432 if (enumerator
->priv
->outstanding_callback
)
433 (*enumerator
->priv
->outstanding_callback
) (source_object
, res
, user_data
);
434 g_object_unref (enumerator
);
438 * g_file_enumerator_close_async:
439 * @enumerator: a #GFileEnumerator.
440 * @io_priority: the <link linkend="io-priority">I/O priority</link>
442 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
443 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
444 * @user_data: (closure): the data to pass to callback function
446 * Asynchronously closes the file enumerator.
448 * If @cancellable is not %NULL, then the operation can be cancelled by
449 * triggering the cancellable object from another thread. If the operation
450 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
451 * g_file_enumerator_close_finish().
454 g_file_enumerator_close_async (GFileEnumerator
*enumerator
,
456 GCancellable
*cancellable
,
457 GAsyncReadyCallback callback
,
460 GFileEnumeratorClass
*class;
462 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator
));
464 if (enumerator
->priv
->closed
)
466 g_simple_async_report_error_in_idle (G_OBJECT (enumerator
),
469 G_IO_ERROR
, G_IO_ERROR_CLOSED
,
470 _("File enumerator is already closed"));
474 if (enumerator
->priv
->pending
)
476 g_simple_async_report_error_in_idle (G_OBJECT (enumerator
),
479 G_IO_ERROR
, G_IO_ERROR_PENDING
,
480 _("File enumerator has outstanding operation"));
484 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
486 enumerator
->priv
->pending
= TRUE
;
487 enumerator
->priv
->outstanding_callback
= callback
;
488 g_object_ref (enumerator
);
489 (* class->close_async
) (enumerator
, io_priority
, cancellable
,
490 close_async_callback_wrapper
, user_data
);
494 * g_file_enumerator_close_finish:
495 * @enumerator: a #GFileEnumerator.
496 * @result: a #GAsyncResult.
497 * @error: a #GError location to store the error occurring, or %NULL to
500 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
502 * If the file enumerator was already closed when g_file_enumerator_close_async()
503 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
504 * return %FALSE. If the file enumerator had pending operation when the close
505 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
506 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
507 * cancelled by triggering the cancellable object from another thread. If the operation
508 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
511 * Returns: %TRUE if the close operation has finished successfully.
514 g_file_enumerator_close_finish (GFileEnumerator
*enumerator
,
515 GAsyncResult
*result
,
518 GSimpleAsyncResult
*simple
;
519 GFileEnumeratorClass
*class;
521 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), FALSE
);
522 g_return_val_if_fail (G_IS_ASYNC_RESULT (result
), FALSE
);
524 if (G_IS_SIMPLE_ASYNC_RESULT (result
))
526 simple
= G_SIMPLE_ASYNC_RESULT (result
);
527 if (g_simple_async_result_propagate_error (simple
, error
))
531 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator
);
532 return class->close_finish (enumerator
, result
, error
);
536 * g_file_enumerator_is_closed:
537 * @enumerator: a #GFileEnumerator.
539 * Checks if the file enumerator has been closed.
541 * Returns: %TRUE if the @enumerator is closed.
544 g_file_enumerator_is_closed (GFileEnumerator
*enumerator
)
546 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), TRUE
);
548 return enumerator
->priv
->closed
;
552 * g_file_enumerator_has_pending:
553 * @enumerator: a #GFileEnumerator.
555 * Checks if the file enumerator has pending operations.
557 * Returns: %TRUE if the @enumerator has pending operations.
560 g_file_enumerator_has_pending (GFileEnumerator
*enumerator
)
562 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), TRUE
);
564 return enumerator
->priv
->pending
;
568 * g_file_enumerator_set_pending:
569 * @enumerator: a #GFileEnumerator.
570 * @pending: a boolean value.
572 * Sets the file enumerator as having pending operations.
575 g_file_enumerator_set_pending (GFileEnumerator
*enumerator
,
578 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator
));
580 enumerator
->priv
->pending
= pending
;
584 * g_file_enumerator_get_container:
585 * @enumerator: a #GFileEnumerator
587 * Get the #GFile container which is being enumerated.
589 * Returns: (transfer none): the #GFile which is being enumerated.
594 g_file_enumerator_get_container (GFileEnumerator
*enumerator
)
596 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator
), NULL
);
598 return enumerator
->priv
->container
;
607 next_async_op_free (NextAsyncOp
*op
)
609 /* Free the list, if finish wasn't called */
610 g_list_foreach (op
->files
, (GFunc
)g_object_unref
, NULL
);
611 g_list_free (op
->files
);
619 next_files_thread (GSimpleAsyncResult
*res
,
621 GCancellable
*cancellable
)
624 GFileEnumeratorClass
*class;
625 GError
*error
= NULL
;
627 GFileEnumerator
*enumerator
;
630 enumerator
= G_FILE_ENUMERATOR (object
);
631 op
= g_simple_async_result_get_op_res_gpointer (res
);
633 class = G_FILE_ENUMERATOR_GET_CLASS (object
);
635 for (i
= 0; i
< op
->num_files
; i
++)
637 if (g_cancellable_set_error_if_cancelled (cancellable
, &error
))
640 info
= class->next_file (enumerator
, cancellable
, &error
);
644 /* If we get an error after first file, return that on next operation */
645 if (error
!= NULL
&& i
> 0)
647 if (error
->domain
== G_IO_ERROR
&&
648 error
->code
== G_IO_ERROR_CANCELLED
)
649 g_error_free (error
); /* Never propagate cancel errors to other call */
651 enumerator
->priv
->outstanding_error
= error
;
658 op
->files
= g_list_prepend (op
->files
, info
);
663 g_file_enumerator_real_next_files_async (GFileEnumerator
*enumerator
,
666 GCancellable
*cancellable
,
667 GAsyncReadyCallback callback
,
670 GSimpleAsyncResult
*res
;
673 op
= g_new0 (NextAsyncOp
, 1);
675 op
->num_files
= num_files
;
678 res
= g_simple_async_result_new (G_OBJECT (enumerator
), callback
, user_data
, g_file_enumerator_real_next_files_async
);
679 g_simple_async_result_set_op_res_gpointer (res
, op
, (GDestroyNotify
) next_async_op_free
);
681 g_simple_async_result_run_in_thread (res
, next_files_thread
, io_priority
, cancellable
);
682 g_object_unref (res
);
686 g_file_enumerator_real_next_files_finish (GFileEnumerator
*enumerator
,
687 GAsyncResult
*result
,
690 GSimpleAsyncResult
*simple
= G_SIMPLE_ASYNC_RESULT (result
);
694 g_warn_if_fail (g_simple_async_result_get_source_tag (simple
) ==
695 g_file_enumerator_real_next_files_async
);
697 op
= g_simple_async_result_get_op_res_gpointer (simple
);
705 close_async_thread (GSimpleAsyncResult
*res
,
707 GCancellable
*cancellable
)
709 GFileEnumeratorClass
*class;
710 GError
*error
= NULL
;
713 /* Auto handling of cancelation disabled, and ignore
714 cancellation, since we want to close things anyway, although
715 possibly in a quick-n-dirty way. At least we never want to leak
718 class = G_FILE_ENUMERATOR_GET_CLASS (object
);
719 result
= class->close_fn (G_FILE_ENUMERATOR (object
), cancellable
, &error
);
721 g_simple_async_result_take_error (res
, 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
);