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
36 * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s, returning
37 * a #GFileInfo structure for each file enumerated (e.g. g_file_enumerate_children()
38 * will return a #GFileEnumerator for each of the children within a directory).
40 * To get the next file's information from a #GFileEnumerator, use
41 * g_file_enumerator_next_file() or its asynchronous version,
42 * g_file_enumerator_next_file_async(). Note that the asynchronous version will
43 * return a list of #GFileInfo<!---->s, whereas the synchronous will only return
44 * the next file in the enumerator.
46 * To close a #GFileEnumerator, use g_file_enumerator_close(), or its asynchronous
47 * version, g_file_enumerator_close_async(). Once a #GFileEnumerator is closed,
48 * no further actions may be performed on it, and it should be freed with g_object_unref().
52 G_DEFINE_TYPE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT);
54 struct _GFileEnumeratorPrivate {
55 /* TODO: Should be public for subclasses? */
58 GAsyncReadyCallback outstanding_callback;
59 GError *outstanding_error;
62 static void g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
65 GCancellable *cancellable,
66 GAsyncReadyCallback callback,
68 static GList * g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
71 static void g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
73 GCancellable *cancellable,
74 GAsyncReadyCallback callback,
76 static gboolean g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
81 g_file_enumerator_finalize (GObject *object)
83 GFileEnumerator *enumerator;
85 enumerator = G_FILE_ENUMERATOR (object);
87 if (!enumerator->priv->closed)
88 g_file_enumerator_close (enumerator, NULL, NULL);
90 if (G_OBJECT_CLASS (g_file_enumerator_parent_class)->finalize)
91 (*G_OBJECT_CLASS (g_file_enumerator_parent_class)->finalize) (object);
95 g_file_enumerator_class_init (GFileEnumeratorClass *klass)
97 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
99 g_type_class_add_private (klass, sizeof (GFileEnumeratorPrivate));
101 gobject_class->finalize = g_file_enumerator_finalize;
103 klass->next_files_async = g_file_enumerator_real_next_files_async;
104 klass->next_files_finish = g_file_enumerator_real_next_files_finish;
105 klass->close_async = g_file_enumerator_real_close_async;
106 klass->close_finish = g_file_enumerator_real_close_finish;
110 g_file_enumerator_init (GFileEnumerator *enumerator)
112 enumerator->priv = G_TYPE_INSTANCE_GET_PRIVATE (enumerator,
113 G_TYPE_FILE_ENUMERATOR,
114 GFileEnumeratorPrivate);
118 * g_file_enumerator_next_file:
119 * @enumerator: a #GFileEnumerator.
120 * @cancellable: optional #GCancellable object, %NULL to ignore.
121 * @error: location to store the error occuring, or %NULL to ignore
123 * Returns information for the next file in the enumerated object.
124 * Will block until the information is available. The #GFileInfo
125 * returned from this function will contain attributes that match the
126 * attribute string that was passed when the #GFileEnumerator was created.
128 * On error, returns %NULL and sets @error to the error. If the
129 * enumerator is at the end, %NULL will be returned and @error will
132 * Return value: A #GFileInfo or %NULL on error or end of enumerator
135 g_file_enumerator_next_file (GFileEnumerator *enumerator,
136 GCancellable *cancellable,
139 GFileEnumeratorClass *class;
142 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
143 g_return_val_if_fail (enumerator != NULL, NULL);
145 if (enumerator->priv->closed)
147 g_set_error (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
148 _("Enumerator is closed"));
152 if (enumerator->priv->pending)
154 g_set_error (error, G_IO_ERROR, G_IO_ERROR_PENDING,
155 _("File enumerator has outstanding operation"));
159 if (enumerator->priv->outstanding_error)
161 g_propagate_error (error, enumerator->priv->outstanding_error);
162 enumerator->priv->outstanding_error = NULL;
166 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
169 g_push_current_cancellable (cancellable);
171 enumerator->priv->pending = TRUE;
172 info = (* class->next_file) (enumerator, cancellable, error);
173 enumerator->priv->pending = FALSE;
176 g_pop_current_cancellable (cancellable);
182 * g_file_enumerator_close:
183 * @enumerator: a #GFileEnumerator.
184 * @cancellable: optional #GCancellable object, %NULL to ignore.
185 * @error: location to store the error occuring, or %NULL to ignore
187 * Releases all resources used by this enumerator, making the
188 * enumerator return %G_IO_ERROR_CLOSED on all calls.
190 * This will be automatically called when the last reference
191 * is dropped, but you might want to call make sure resources
192 * are released as early as possible.
194 * Return value: #TRUE on success or #FALSE on error.
197 g_file_enumerator_close (GFileEnumerator *enumerator,
198 GCancellable *cancellable,
201 GFileEnumeratorClass *class;
203 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
204 g_return_val_if_fail (enumerator != NULL, FALSE);
206 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
208 if (enumerator->priv->closed)
211 if (enumerator->priv->pending)
213 g_set_error (error, G_IO_ERROR, G_IO_ERROR_PENDING,
214 _("File enumerator has outstanding operation"));
219 g_push_current_cancellable (cancellable);
221 enumerator->priv->pending = TRUE;
222 (* class->close_fn) (enumerator, cancellable, error);
223 enumerator->priv->pending = FALSE;
224 enumerator->priv->closed = TRUE;
227 g_pop_current_cancellable (cancellable);
233 next_async_callback_wrapper (GObject *source_object,
237 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
239 enumerator->priv->pending = FALSE;
240 if (enumerator->priv->outstanding_callback)
241 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
242 g_object_unref (enumerator);
246 * g_file_enumerator_next_files_async:
247 * @enumerator: a #GFileEnumerator.
248 * @num_files: the number of file info objects to request
249 * @io_priority: the <link linkend="gioscheduler">io priority</link>
251 * @cancellable: optional #GCancellable object, %NULL to ignore.
252 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
253 * @user_data: the data to pass to callback function
255 * Request information for a number of files from the enumerator asynchronously.
256 * When all i/o for the operation is finished the @callback will be called with
257 * the requested information.
259 * The callback can be called with less than @num_files files in case of error
260 * or at the end of the enumerator. In case of a partial error the callback will
261 * be called with any succeeding items and no error, and on the next request the
262 * error will be reported. If a request is cancelled the callback will be called
263 * with %G_IO_ERROR_CANCELLED.
265 * During an async request no other sync and async calls are allowed, and will
266 * result in %G_IO_ERROR_PENDING errors.
268 * Any outstanding i/o request with higher priority (lower numerical value) will
269 * be executed before an outstanding request with lower priority. Default
270 * priority is %G_PRIORITY_DEFAULT.
273 g_file_enumerator_next_files_async (GFileEnumerator *enumerator,
276 GCancellable *cancellable,
277 GAsyncReadyCallback callback,
280 GFileEnumeratorClass *class;
281 GSimpleAsyncResult *simple;
283 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
284 g_return_if_fail (enumerator != NULL);
285 g_return_if_fail (num_files >= 0);
289 simple = g_simple_async_result_new (G_OBJECT (enumerator),
292 g_file_enumerator_next_files_async);
293 g_simple_async_result_complete_in_idle (simple);
294 g_object_unref (simple);
298 if (enumerator->priv->closed)
300 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
303 G_IO_ERROR, G_IO_ERROR_CLOSED,
304 _("File enumerator is already closed"));
308 if (enumerator->priv->pending)
310 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
313 G_IO_ERROR, G_IO_ERROR_PENDING,
314 _("File enumerator has outstanding operation"));
318 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
320 enumerator->priv->pending = TRUE;
321 enumerator->priv->outstanding_callback = callback;
322 g_object_ref (enumerator);
323 (* class->next_files_async) (enumerator, num_files, io_priority, cancellable,
324 next_async_callback_wrapper, user_data);
328 * g_file_enumerator_next_files_finish:
329 * @enumerator: a #GFileEnumerator.
330 * @result: a #GAsyncResult.
331 * @error: a #GError location to store the error occuring, or %NULL to
334 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
336 * Returns: a #GList of #GFileInfo<!---->s.
339 g_file_enumerator_next_files_finish (GFileEnumerator *enumerator,
340 GAsyncResult *result,
343 GFileEnumeratorClass *class;
344 GSimpleAsyncResult *simple;
346 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
347 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
349 if (G_IS_SIMPLE_ASYNC_RESULT (result))
351 simple = G_SIMPLE_ASYNC_RESULT (result);
352 if (g_simple_async_result_propagate_error (simple, error))
355 /* Special case read of 0 files */
356 if (g_simple_async_result_get_source_tag (simple) == g_file_enumerator_next_files_async)
360 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
361 return class->next_files_finish (enumerator, result, error);
365 close_async_callback_wrapper (GObject *source_object,
369 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
371 enumerator->priv->pending = FALSE;
372 enumerator->priv->closed = TRUE;
373 if (enumerator->priv->outstanding_callback)
374 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
375 g_object_unref (enumerator);
379 * g_file_enumerator_close_async:
380 * @enumerator: a #GFileEnumerator.
381 * @io_priority: the <link linkend="io-priority">I/O priority</link>
383 * @cancellable: optional #GCancellable object, %NULL to ignore.
384 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
385 * @user_data: the data to pass to callback function
387 * Asynchronously closes the file enumerator.
389 * If @cancellable is not %NULL, then the operation can be cancelled by
390 * triggering the cancellable object from another thread. If the operation
391 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
392 * g_file_enumerator_close_finish().
395 g_file_enumerator_close_async (GFileEnumerator *enumerator,
397 GCancellable *cancellable,
398 GAsyncReadyCallback callback,
401 GFileEnumeratorClass *class;
403 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
405 if (enumerator->priv->closed)
407 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
410 G_IO_ERROR, G_IO_ERROR_CLOSED,
411 _("File enumerator is already closed"));
415 if (enumerator->priv->pending)
417 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
420 G_IO_ERROR, G_IO_ERROR_PENDING,
421 _("File enumerator has outstanding operation"));
425 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
427 enumerator->priv->pending = TRUE;
428 enumerator->priv->outstanding_callback = callback;
429 g_object_ref (enumerator);
430 (* class->close_async) (enumerator, io_priority, cancellable,
431 close_async_callback_wrapper, user_data);
435 * g_file_enumerator_close_finish:
436 * @enumerator: a #GFileEnumerator.
437 * @result: a #GAsyncResult.
438 * @error: a #GError location to store the error occuring, or %NULL to
441 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
443 * If the file enumerator was already closed when g_file_enumerator_close_async()
444 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
445 * return %FALSE. If the file enumerator had pending operation when the close
446 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
447 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
448 * cancelled by triggering the cancellable object from another thread. If the operation
449 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
452 * Returns: %TRUE if the close operation has finished successfully.
455 g_file_enumerator_close_finish (GFileEnumerator *enumerator,
456 GAsyncResult *result,
459 GSimpleAsyncResult *simple;
460 GFileEnumeratorClass *class;
462 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
463 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
465 if (G_IS_SIMPLE_ASYNC_RESULT (result))
467 simple = G_SIMPLE_ASYNC_RESULT (result);
468 if (g_simple_async_result_propagate_error (simple, error))
472 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
473 return class->close_finish (enumerator, result, error);
477 * g_file_enumerator_is_closed:
478 * @enumerator: a #GFileEnumerator.
480 * Checks if the file enumerator has been closed.
482 * Returns: %TRUE if the @enumerator is closed.
485 g_file_enumerator_is_closed (GFileEnumerator *enumerator)
487 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
489 return enumerator->priv->closed;
493 * g_file_enumerator_has_pending:
494 * @enumerator: a #GFileEnumerator.
496 * Checks if the file enumerator has pending operations.
498 * Returns: %TRUE if the @enumerator has pending operations.
501 g_file_enumerator_has_pending (GFileEnumerator *enumerator)
503 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
505 return enumerator->priv->pending;
509 * g_file_enumerator_set_pending:
510 * @enumerator: a #GFileEnumerator.
511 * @pending: a boolean value.
513 * Sets the file enumerator as having pending operations.
516 g_file_enumerator_set_pending (GFileEnumerator *enumerator,
519 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
521 enumerator->priv->pending = pending;
530 next_files_thread (GSimpleAsyncResult *res,
532 GCancellable *cancellable)
535 GFileEnumeratorClass *class;
536 GError *error = NULL;
538 GFileEnumerator *enumerator;
541 enumerator = G_FILE_ENUMERATOR (object);
542 op = g_simple_async_result_get_op_res_gpointer (res);
544 class = G_FILE_ENUMERATOR_GET_CLASS (object);
546 for (i = 0; i < op->num_files; i++)
548 if (g_cancellable_set_error_if_cancelled (cancellable, &error))
551 info = class->next_file (enumerator, cancellable, &error);
555 /* If we get an error after first file, return that on next operation */
556 if (error != NULL && i > 0)
558 if (error->domain == G_IO_ERROR &&
559 error->code == G_IO_ERROR_CANCELLED)
560 g_error_free (error); /* Never propagate cancel errors to other call */
562 enumerator->priv->outstanding_error = error;
569 op->files = g_list_prepend (op->files, info);
575 g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
578 GCancellable *cancellable,
579 GAsyncReadyCallback callback,
582 GSimpleAsyncResult *res;
585 op = g_new0 (NextAsyncOp, 1);
587 op->num_files = num_files;
590 res = g_simple_async_result_new (G_OBJECT (enumerator), callback, user_data, g_file_enumerator_real_next_files_async);
591 g_simple_async_result_set_op_res_gpointer (res, op, g_free);
593 g_simple_async_result_run_in_thread (res, next_files_thread, io_priority, cancellable);
594 g_object_unref (res);
598 g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
599 GAsyncResult *result,
602 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
605 g_assert (g_simple_async_result_get_source_tag (simple) ==
606 g_file_enumerator_real_next_files_async);
608 op = g_simple_async_result_get_op_res_gpointer (simple);
614 close_async_thread (GSimpleAsyncResult *res,
616 GCancellable *cancellable)
618 GFileEnumeratorClass *class;
619 GError *error = NULL;
622 /* Auto handling of cancelation disabled, and ignore
623 cancellation, since we want to close things anyway, although
624 possibly in a quick-n-dirty way. At least we never want to leak
627 class = G_FILE_ENUMERATOR_GET_CLASS (object);
628 result = class->close_fn (G_FILE_ENUMERATOR (object), cancellable, &error);
631 g_simple_async_result_set_from_error (res, error);
632 g_error_free (error);
638 g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
640 GCancellable *cancellable,
641 GAsyncReadyCallback callback,
644 GSimpleAsyncResult *res;
646 res = g_simple_async_result_new (G_OBJECT (enumerator),
649 g_file_enumerator_real_close_async);
651 g_simple_async_result_set_handle_cancellation (res, FALSE);
653 g_simple_async_result_run_in_thread (res,
657 g_object_unref (res);
661 g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
662 GAsyncResult *result,
665 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
666 g_assert (g_simple_async_result_get_source_tag (simple) ==
667 g_file_enumerator_real_close_async);
671 #define __G_FILE_ENUMERATOR_C__
672 #include "gioaliasdef.c"