regex: Update included PCRE to 8.30
[glib.git] / gio / gfileenumerator.c
blob654c691138bed3a646c709fdf42ecc6f127ee2a1
1 /* GIO - GLib Input, Output and Streaming Library
2 *
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>
23 #include "config.h"
24 #include "gfileenumerator.h"
25 #include "gfile.h"
26 #include "gioscheduler.h"
27 #include "gasyncresult.h"
28 #include "gasynchelper.h"
29 #include "gsimpleasyncresult.h"
30 #include "gioerror.h"
31 #include "glibintl.h"
34 /**
35 * SECTION:gfileenumerator
36 * @short_description: Enumerated Files Routines
37 * @include: gio/gio.h
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().
55 **/
57 G_DEFINE_TYPE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT);
59 struct _GFileEnumeratorPrivate {
60 /* TODO: Should be public for subclasses? */
61 GFile *container;
62 guint closed : 1;
63 guint pending : 1;
64 GAsyncReadyCallback outstanding_callback;
65 GError *outstanding_error;
68 enum {
69 PROP_0,
70 PROP_CONTAINER
73 static void g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
74 int num_files,
75 int io_priority,
76 GCancellable *cancellable,
77 GAsyncReadyCallback callback,
78 gpointer user_data);
79 static GList * g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
80 GAsyncResult *res,
81 GError **error);
82 static void g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
83 int io_priority,
84 GCancellable *cancellable,
85 GAsyncReadyCallback callback,
86 gpointer user_data);
87 static gboolean g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
88 GAsyncResult *res,
89 GError **error);
91 static void
92 g_file_enumerator_set_property (GObject *object,
93 guint property_id,
94 const GValue *value,
95 GParamSpec *pspec)
97 GFileEnumerator *enumerator;
99 enumerator = G_FILE_ENUMERATOR (object);
101 switch (property_id) {
102 case PROP_CONTAINER:
103 enumerator->priv->container = g_value_dup_object (value);
104 break;
105 default:
106 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
107 break;
111 static void
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);
126 static void
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);
139 static void
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"),
159 G_TYPE_FILE,
160 G_PARAM_WRITABLE |
161 G_PARAM_CONSTRUCT_ONLY |
162 G_PARAM_STATIC_STRINGS));
165 static void
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
186 * be unset.
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.
191 GFileInfo *
192 g_file_enumerator_next_file (GFileEnumerator *enumerator,
193 GCancellable *cancellable,
194 GError **error)
196 GFileEnumeratorClass *class;
197 GFileInfo *info;
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"));
206 return NULL;
209 if (enumerator->priv->pending)
211 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
212 _("File enumerator has outstanding operation"));
213 return NULL;
216 if (enumerator->priv->outstanding_error)
218 g_propagate_error (error, enumerator->priv->outstanding_error);
219 enumerator->priv->outstanding_error = NULL;
220 return NULL;
223 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
225 if (cancellable)
226 g_cancellable_push_current (cancellable);
228 enumerator->priv->pending = TRUE;
229 info = (* class->next_file) (enumerator, cancellable, error);
230 enumerator->priv->pending = FALSE;
232 if (cancellable)
233 g_cancellable_pop_current (cancellable);
235 return info;
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.
253 gboolean
254 g_file_enumerator_close (GFileEnumerator *enumerator,
255 GCancellable *cancellable,
256 GError **error)
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)
266 return TRUE;
268 if (enumerator->priv->pending)
270 g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
271 _("File enumerator has outstanding operation"));
272 return FALSE;
275 if (cancellable)
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;
283 if (cancellable)
284 g_cancellable_pop_current (cancellable);
286 return TRUE;
289 static void
290 next_async_callback_wrapper (GObject *source_object,
291 GAsyncResult *res,
292 gpointer user_data)
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>
307 * of the request.
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.
329 void
330 g_file_enumerator_next_files_async (GFileEnumerator *enumerator,
331 int num_files,
332 int io_priority,
333 GCancellable *cancellable,
334 GAsyncReadyCallback callback,
335 gpointer user_data)
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);
344 if (num_files == 0)
346 simple = g_simple_async_result_new (G_OBJECT (enumerator),
347 callback,
348 user_data,
349 g_file_enumerator_next_files_async);
350 g_simple_async_result_complete_in_idle (simple);
351 g_object_unref (simple);
352 return;
355 if (enumerator->priv->closed)
357 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
358 callback,
359 user_data,
360 G_IO_ERROR, G_IO_ERROR_CLOSED,
361 _("File enumerator is already closed"));
362 return;
365 if (enumerator->priv->pending)
367 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
368 callback,
369 user_data,
370 G_IO_ERROR, G_IO_ERROR_PENDING,
371 _("File enumerator has outstanding operation"));
372 return;
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
389 * ignore.
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
395 * done with them.
397 GList *
398 g_file_enumerator_next_files_finish (GFileEnumerator *enumerator,
399 GAsyncResult *result,
400 GError **error)
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))
412 return NULL;
414 /* Special case read of 0 files */
415 if (g_simple_async_result_get_source_tag (simple) == g_file_enumerator_next_files_async)
416 return NULL;
419 class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
420 return class->next_files_finish (enumerator, result, error);
423 static void
424 close_async_callback_wrapper (GObject *source_object,
425 GAsyncResult *res,
426 gpointer user_data)
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>
441 * of the request.
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().
453 void
454 g_file_enumerator_close_async (GFileEnumerator *enumerator,
455 int io_priority,
456 GCancellable *cancellable,
457 GAsyncReadyCallback callback,
458 gpointer user_data)
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),
467 callback,
468 user_data,
469 G_IO_ERROR, G_IO_ERROR_CLOSED,
470 _("File enumerator is already closed"));
471 return;
474 if (enumerator->priv->pending)
476 g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
477 callback,
478 user_data,
479 G_IO_ERROR, G_IO_ERROR_PENDING,
480 _("File enumerator has outstanding operation"));
481 return;
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
498 * ignore.
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
509 * returned.
511 * Returns: %TRUE if the close operation has finished successfully.
513 gboolean
514 g_file_enumerator_close_finish (GFileEnumerator *enumerator,
515 GAsyncResult *result,
516 GError **error)
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))
528 return FALSE;
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.
543 gboolean
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.
559 gboolean
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.
574 void
575 g_file_enumerator_set_pending (GFileEnumerator *enumerator,
576 gboolean pending)
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.
591 * Since: 2.18
593 GFile *
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;
601 typedef struct {
602 int num_files;
603 GList *files;
604 } NextAsyncOp;
606 static void
607 next_async_op_free (NextAsyncOp *op)
609 /* Free the list, if finish wasn't called */
610 g_list_free_full (op->files, g_object_unref);
612 g_free (op);
617 static void
618 next_files_thread (GSimpleAsyncResult *res,
619 GObject *object,
620 GCancellable *cancellable)
622 NextAsyncOp *op;
623 GFileEnumeratorClass *class;
624 GError *error = NULL;
625 GFileInfo *info;
626 GFileEnumerator *enumerator;
627 int i;
629 enumerator = G_FILE_ENUMERATOR (object);
630 op = g_simple_async_result_get_op_res_gpointer (res);
632 class = G_FILE_ENUMERATOR_GET_CLASS (object);
634 for (i = 0; i < op->num_files; i++)
636 if (g_cancellable_set_error_if_cancelled (cancellable, &error))
637 info = NULL;
638 else
639 info = class->next_file (enumerator, cancellable, &error);
641 if (info == NULL)
643 /* If we get an error after first file, return that on next operation */
644 if (error != NULL && i > 0)
646 if (error->domain == G_IO_ERROR &&
647 error->code == G_IO_ERROR_CANCELLED)
648 g_error_free (error); /* Never propagate cancel errors to other call */
649 else
650 enumerator->priv->outstanding_error = error;
651 error = NULL;
654 break;
656 else
657 op->files = g_list_prepend (op->files, info);
661 static void
662 g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
663 int num_files,
664 int io_priority,
665 GCancellable *cancellable,
666 GAsyncReadyCallback callback,
667 gpointer user_data)
669 GSimpleAsyncResult *res;
670 NextAsyncOp *op;
672 op = g_new0 (NextAsyncOp, 1);
674 op->num_files = num_files;
675 op->files = NULL;
677 res = g_simple_async_result_new (G_OBJECT (enumerator), callback, user_data, g_file_enumerator_real_next_files_async);
678 g_simple_async_result_set_op_res_gpointer (res, op, (GDestroyNotify) next_async_op_free);
680 g_simple_async_result_run_in_thread (res, next_files_thread, io_priority, cancellable);
681 g_object_unref (res);
684 static GList *
685 g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
686 GAsyncResult *result,
687 GError **error)
689 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
690 NextAsyncOp *op;
691 GList *res;
693 g_warn_if_fail (g_simple_async_result_get_source_tag (simple) ==
694 g_file_enumerator_real_next_files_async);
696 op = g_simple_async_result_get_op_res_gpointer (simple);
698 res = op->files;
699 op->files = NULL;
700 return res;
703 static void
704 close_async_thread (GSimpleAsyncResult *res,
705 GObject *object,
706 GCancellable *cancellable)
708 GFileEnumeratorClass *class;
709 GError *error = NULL;
710 gboolean result;
712 /* Auto handling of cancelation disabled, and ignore
713 cancellation, since we want to close things anyway, although
714 possibly in a quick-n-dirty way. At least we never want to leak
715 open handles */
717 class = G_FILE_ENUMERATOR_GET_CLASS (object);
718 result = class->close_fn (G_FILE_ENUMERATOR (object), cancellable, &error);
719 if (!result)
720 g_simple_async_result_take_error (res, error);
724 static void
725 g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
726 int io_priority,
727 GCancellable *cancellable,
728 GAsyncReadyCallback callback,
729 gpointer user_data)
731 GSimpleAsyncResult *res;
733 res = g_simple_async_result_new (G_OBJECT (enumerator),
734 callback,
735 user_data,
736 g_file_enumerator_real_close_async);
738 g_simple_async_result_set_handle_cancellation (res, FALSE);
740 g_simple_async_result_run_in_thread (res,
741 close_async_thread,
742 io_priority,
743 cancellable);
744 g_object_unref (res);
747 static gboolean
748 g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
749 GAsyncResult *result,
750 GError **error)
752 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
753 g_warn_if_fail (g_simple_async_result_get_source_tag (simple) ==
754 g_file_enumerator_real_close_async);
755 return TRUE;