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? */
61 GAsyncReadyCallback outstanding_callback;
62 GError *outstanding_error;
65 static void g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
68 GCancellable *cancellable,
69 GAsyncReadyCallback callback,
71 static GList * g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
74 static void g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
76 GCancellable *cancellable,
77 GAsyncReadyCallback callback,
79 static gboolean g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
84 g_file_enumerator_finalize (GObject *object)
86 GFileEnumerator *enumerator;
88 enumerator = G_FILE_ENUMERATOR (object);
90 if (!enumerator->priv->closed)
91 g_file_enumerator_close (enumerator, NULL, NULL);
93 if (G_OBJECT_CLASS (g_file_enumerator_parent_class)->finalize)
94 (*G_OBJECT_CLASS (g_file_enumerator_parent_class)->finalize) (object);
98 g_file_enumerator_class_init (GFileEnumeratorClass *klass)
100 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
102 g_type_class_add_private (klass, sizeof (GFileEnumeratorPrivate));
104 gobject_class->finalize = g_file_enumerator_finalize;
106 klass->next_files_async = g_file_enumerator_real_next_files_async;
107 klass->next_files_finish = g_file_enumerator_real_next_files_finish;
108 klass->close_async = g_file_enumerator_real_close_async;
109 klass->close_finish = g_file_enumerator_real_close_finish;
113 g_file_enumerator_init (GFileEnumerator *enumerator)
115 enumerator->priv = G_TYPE_INSTANCE_GET_PRIVATE (enumerator,
116 G_TYPE_FILE_ENUMERATOR,
117 GFileEnumeratorPrivate);
121 * g_file_enumerator_next_file:
122 * @enumerator: a #GFileEnumerator.
123 * @cancellable: optional #GCancellable object, %NULL to ignore.
124 * @error: location to store the error occuring, or %NULL to ignore
126 * Returns information for the next file in the enumerated object.
127 * Will block until the information is available. The #GFileInfo
128 * returned from this function will contain attributes that match the
129 * attribute string that was passed when the #GFileEnumerator was created.
131 * On error, returns %NULL and sets @error to the error. If the
132 * enumerator is at the end, %NULL will be returned and @error will
135 * Return value: A #GFileInfo or %NULL on error or end of enumerator
138 g_file_enumerator_next_file (GFileEnumerator *enumerator,
139 GCancellable *cancellable,
142 GFileEnumeratorClass *class;
145 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
146 g_return_val_if_fail (enumerator != NULL, NULL);
148 if (enumerator->priv->closed)
150 g_set_error (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
151 _("Enumerator is closed"));
155 if (enumerator->priv->pending)
157 g_set_error (error, G_IO_ERROR, G_IO_ERROR_PENDING,
158 _("File enumerator has outstanding operation"));
162 if (enumerator->priv->outstanding_error)
164 g_propagate_error (error, enumerator->priv->outstanding_error);
165 enumerator->priv->outstanding_error = NULL;
169 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
172 g_cancellable_push_current (cancellable);
174 enumerator->priv->pending = TRUE;
175 info = (* class->next_file) (enumerator, cancellable, error);
176 enumerator->priv->pending = FALSE;
179 g_cancellable_pop_current (cancellable);
185 * g_file_enumerator_close:
186 * @enumerator: a #GFileEnumerator.
187 * @cancellable: optional #GCancellable object, %NULL to ignore.
188 * @error: location to store the error occuring, or %NULL to ignore
190 * Releases all resources used by this enumerator, making the
191 * enumerator return %G_IO_ERROR_CLOSED on all calls.
193 * This will be automatically called when the last reference
194 * is dropped, but you might want to call this function to make
195 * sure resources are released as early as possible.
197 * Return value: #TRUE on success or #FALSE on error.
200 g_file_enumerator_close (GFileEnumerator *enumerator,
201 GCancellable *cancellable,
204 GFileEnumeratorClass *class;
206 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
207 g_return_val_if_fail (enumerator != NULL, FALSE);
209 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
211 if (enumerator->priv->closed)
214 if (enumerator->priv->pending)
216 g_set_error (error, G_IO_ERROR, G_IO_ERROR_PENDING,
217 _("File enumerator has outstanding operation"));
222 g_cancellable_push_current (cancellable);
224 enumerator->priv->pending = TRUE;
225 (* class->close_fn) (enumerator, cancellable, error);
226 enumerator->priv->pending = FALSE;
227 enumerator->priv->closed = TRUE;
230 g_cancellable_pop_current (cancellable);
236 next_async_callback_wrapper (GObject *source_object,
240 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
242 enumerator->priv->pending = FALSE;
243 if (enumerator->priv->outstanding_callback)
244 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
245 g_object_unref (enumerator);
249 * g_file_enumerator_next_files_async:
250 * @enumerator: a #GFileEnumerator.
251 * @num_files: the number of file info objects to request
252 * @io_priority: the <link linkend="gioscheduler">io priority</link>
254 * @cancellable: optional #GCancellable object, %NULL to ignore.
255 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
256 * @user_data: the data to pass to callback function
258 * Request information for a number of files from the enumerator asynchronously.
259 * When all i/o for the operation is finished the @callback will be called with
260 * the requested information.
262 * The callback can be called with less than @num_files files in case of error
263 * or at the end of the enumerator. In case of a partial error the callback will
264 * be called with any succeeding items and no error, and on the next request the
265 * error will be reported. If a request is cancelled the callback will be called
266 * with %G_IO_ERROR_CANCELLED.
268 * During an async request no other sync and async calls are allowed, and will
269 * result in %G_IO_ERROR_PENDING errors.
271 * Any outstanding i/o request with higher priority (lower numerical value) will
272 * be executed before an outstanding request with lower priority. Default
273 * priority is %G_PRIORITY_DEFAULT.
276 g_file_enumerator_next_files_async (GFileEnumerator *enumerator,
279 GCancellable *cancellable,
280 GAsyncReadyCallback callback,
283 GFileEnumeratorClass *class;
284 GSimpleAsyncResult *simple;
286 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
287 g_return_if_fail (enumerator != NULL);
288 g_return_if_fail (num_files >= 0);
292 simple = g_simple_async_result_new (G_OBJECT (enumerator),
295 g_file_enumerator_next_files_async);
296 g_simple_async_result_complete_in_idle (simple);
297 g_object_unref (simple);
301 if (enumerator->priv->closed)
303 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
306 G_IO_ERROR, G_IO_ERROR_CLOSED,
307 _("File enumerator is already closed"));
311 if (enumerator->priv->pending)
313 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
316 G_IO_ERROR, G_IO_ERROR_PENDING,
317 _("File enumerator has outstanding operation"));
321 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
323 enumerator->priv->pending = TRUE;
324 enumerator->priv->outstanding_callback = callback;
325 g_object_ref (enumerator);
326 (* class->next_files_async) (enumerator, num_files, io_priority, cancellable,
327 next_async_callback_wrapper, user_data);
331 * g_file_enumerator_next_files_finish:
332 * @enumerator: a #GFileEnumerator.
333 * @result: a #GAsyncResult.
334 * @error: a #GError location to store the error occuring, or %NULL to
337 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
339 * Returns: a #GList of #GFileInfo<!---->s. You must free the list with g_list_free
340 * and unref the infos with g_object_unref when your done with them.
343 g_file_enumerator_next_files_finish (GFileEnumerator *enumerator,
344 GAsyncResult *result,
347 GFileEnumeratorClass *class;
348 GSimpleAsyncResult *simple;
350 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
351 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
353 if (G_IS_SIMPLE_ASYNC_RESULT (result))
355 simple = G_SIMPLE_ASYNC_RESULT (result);
356 if (g_simple_async_result_propagate_error (simple, error))
359 /* Special case read of 0 files */
360 if (g_simple_async_result_get_source_tag (simple) == g_file_enumerator_next_files_async)
364 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
365 return class->next_files_finish (enumerator, result, error);
369 close_async_callback_wrapper (GObject *source_object,
373 GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
375 enumerator->priv->pending = FALSE;
376 enumerator->priv->closed = TRUE;
377 if (enumerator->priv->outstanding_callback)
378 (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
379 g_object_unref (enumerator);
383 * g_file_enumerator_close_async:
384 * @enumerator: a #GFileEnumerator.
385 * @io_priority: the <link linkend="io-priority">I/O priority</link>
387 * @cancellable: optional #GCancellable object, %NULL to ignore.
388 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
389 * @user_data: the data to pass to callback function
391 * Asynchronously closes the file enumerator.
393 * If @cancellable is not %NULL, then the operation can be cancelled by
394 * triggering the cancellable object from another thread. If the operation
395 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
396 * g_file_enumerator_close_finish().
399 g_file_enumerator_close_async (GFileEnumerator *enumerator,
401 GCancellable *cancellable,
402 GAsyncReadyCallback callback,
405 GFileEnumeratorClass *class;
407 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
409 if (enumerator->priv->closed)
411 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
414 G_IO_ERROR, G_IO_ERROR_CLOSED,
415 _("File enumerator is already closed"));
419 if (enumerator->priv->pending)
421 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
424 G_IO_ERROR, G_IO_ERROR_PENDING,
425 _("File enumerator has outstanding operation"));
429 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
431 enumerator->priv->pending = TRUE;
432 enumerator->priv->outstanding_callback = callback;
433 g_object_ref (enumerator);
434 (* class->close_async) (enumerator, io_priority, cancellable,
435 close_async_callback_wrapper, user_data);
439 * g_file_enumerator_close_finish:
440 * @enumerator: a #GFileEnumerator.
441 * @result: a #GAsyncResult.
442 * @error: a #GError location to store the error occuring, or %NULL to
445 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
447 * If the file enumerator was already closed when g_file_enumerator_close_async()
448 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
449 * return %FALSE. If the file enumerator had pending operation when the close
450 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
451 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
452 * cancelled by triggering the cancellable object from another thread. If the operation
453 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
456 * Returns: %TRUE if the close operation has finished successfully.
459 g_file_enumerator_close_finish (GFileEnumerator *enumerator,
460 GAsyncResult *result,
463 GSimpleAsyncResult *simple;
464 GFileEnumeratorClass *class;
466 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
467 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
469 if (G_IS_SIMPLE_ASYNC_RESULT (result))
471 simple = G_SIMPLE_ASYNC_RESULT (result);
472 if (g_simple_async_result_propagate_error (simple, error))
476 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
477 return class->close_finish (enumerator, result, error);
481 * g_file_enumerator_is_closed:
482 * @enumerator: a #GFileEnumerator.
484 * Checks if the file enumerator has been closed.
486 * Returns: %TRUE if the @enumerator is closed.
489 g_file_enumerator_is_closed (GFileEnumerator *enumerator)
491 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
493 return enumerator->priv->closed;
497 * g_file_enumerator_has_pending:
498 * @enumerator: a #GFileEnumerator.
500 * Checks if the file enumerator has pending operations.
502 * Returns: %TRUE if the @enumerator has pending operations.
505 g_file_enumerator_has_pending (GFileEnumerator *enumerator)
507 g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
509 return enumerator->priv->pending;
513 * g_file_enumerator_set_pending:
514 * @enumerator: a #GFileEnumerator.
515 * @pending: a boolean value.
517 * Sets the file enumerator as having pending operations.
520 g_file_enumerator_set_pending (GFileEnumerator *enumerator,
523 g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
525 enumerator->priv->pending = pending;
534 next_async_op_free (NextAsyncOp *op)
536 /* Free the list, if finish wasn't called */
537 g_list_foreach (op->files, (GFunc)g_object_unref, NULL);
538 g_list_free (op->files);
546 next_files_thread (GSimpleAsyncResult *res,
548 GCancellable *cancellable)
551 GFileEnumeratorClass *class;
552 GError *error = NULL;
554 GFileEnumerator *enumerator;
557 enumerator = G_FILE_ENUMERATOR (object);
558 op = g_simple_async_result_get_op_res_gpointer (res);
560 class = G_FILE_ENUMERATOR_GET_CLASS (object);
562 for (i = 0; i < op->num_files; i++)
564 if (g_cancellable_set_error_if_cancelled (cancellable, &error))
567 info = class->next_file (enumerator, cancellable, &error);
571 /* If we get an error after first file, return that on next operation */
572 if (error != NULL && i > 0)
574 if (error->domain == G_IO_ERROR &&
575 error->code == G_IO_ERROR_CANCELLED)
576 g_error_free (error); /* Never propagate cancel errors to other call */
578 enumerator->priv->outstanding_error = error;
585 op->files = g_list_prepend (op->files, info);
590 g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
593 GCancellable *cancellable,
594 GAsyncReadyCallback callback,
597 GSimpleAsyncResult *res;
600 op = g_new0 (NextAsyncOp, 1);
602 op->num_files = num_files;
605 res = g_simple_async_result_new (G_OBJECT (enumerator), callback, user_data, g_file_enumerator_real_next_files_async);
606 g_simple_async_result_set_op_res_gpointer (res, op, (GDestroyNotify) next_async_op_free);
608 g_simple_async_result_run_in_thread (res, next_files_thread, io_priority, cancellable);
609 g_object_unref (res);
613 g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
614 GAsyncResult *result,
617 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
621 g_warn_if_fail (g_simple_async_result_get_source_tag (simple) ==
622 g_file_enumerator_real_next_files_async);
624 op = g_simple_async_result_get_op_res_gpointer (simple);
632 close_async_thread (GSimpleAsyncResult *res,
634 GCancellable *cancellable)
636 GFileEnumeratorClass *class;
637 GError *error = NULL;
640 /* Auto handling of cancelation disabled, and ignore
641 cancellation, since we want to close things anyway, although
642 possibly in a quick-n-dirty way. At least we never want to leak
645 class = G_FILE_ENUMERATOR_GET_CLASS (object);
646 result = class->close_fn (G_FILE_ENUMERATOR (object), cancellable, &error);
649 g_simple_async_result_set_from_error (res, error);
650 g_error_free (error);
656 g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
658 GCancellable *cancellable,
659 GAsyncReadyCallback callback,
662 GSimpleAsyncResult *res;
664 res = g_simple_async_result_new (G_OBJECT (enumerator),
667 g_file_enumerator_real_close_async);
669 g_simple_async_result_set_handle_cancellation (res, FALSE);
671 g_simple_async_result_run_in_thread (res,
675 g_object_unref (res);
679 g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
680 GAsyncResult *result,
683 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
684 g_warn_if_fail (g_simple_async_result_get_source_tag (simple) ==
685 g_file_enumerator_real_close_async);
689 #define __G_FILE_ENUMERATOR_C__
690 #include "gioaliasdef.c"