Documentation: Fixed minor typos and added more mentions of specific
[platform/upstream/glib.git] / gio / gfileenumerator.c
1 /* GIO - GLib Input, Output and Streaming Library
2  * 
3  * Copyright (C) 2006-2007 Red Hat, Inc.
4  *
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.
9  *
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.
14  *
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.
19  *
20  * Author: Alexander Larsson <alexl@redhat.com>
21  */
22
23 #include <config.h>
24 #include "gfileenumerator.h"
25 #include "gioscheduler.h"
26 #include "gasynchelper.h"
27 #include "gsimpleasyncresult.h"
28 #include "glibintl.h"
29
30 #include "gioalias.h"
31
32 /**
33  * SECTION:gfileenumerator
34  * @short_description: Enumerated Files Routines
35  * @include: gio.h
36  * 
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).
41  *
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.
47  *
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().
52  * 
53  **/ 
54
55 G_DEFINE_TYPE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT);
56
57 struct _GFileEnumeratorPrivate {
58   /* TODO: Should be public for subclasses? */
59   guint closed : 1;
60   guint pending : 1;
61   GAsyncReadyCallback outstanding_callback;
62   GError *outstanding_error;
63 };
64
65 static void     g_file_enumerator_real_next_files_async  (GFileEnumerator      *enumerator,
66                                                           int                   num_files,
67                                                           int                   io_priority,
68                                                           GCancellable         *cancellable,
69                                                           GAsyncReadyCallback   callback,
70                                                           gpointer              user_data);
71 static GList *  g_file_enumerator_real_next_files_finish (GFileEnumerator      *enumerator,
72                                                           GAsyncResult         *res,
73                                                           GError              **error);
74 static void     g_file_enumerator_real_close_async       (GFileEnumerator      *enumerator,
75                                                           int                   io_priority,
76                                                           GCancellable         *cancellable,
77                                                           GAsyncReadyCallback   callback,
78                                                           gpointer              user_data);
79 static gboolean g_file_enumerator_real_close_finish      (GFileEnumerator      *enumerator,
80                                                           GAsyncResult         *res,
81                                                           GError              **error);
82
83 static void
84 g_file_enumerator_finalize (GObject *object)
85 {
86   GFileEnumerator *enumerator;
87
88   enumerator = G_FILE_ENUMERATOR (object);
89   
90   if (!enumerator->priv->closed)
91     g_file_enumerator_close (enumerator, NULL, NULL);
92
93   if (G_OBJECT_CLASS (g_file_enumerator_parent_class)->finalize)
94     (*G_OBJECT_CLASS (g_file_enumerator_parent_class)->finalize) (object);
95 }
96
97 static void
98 g_file_enumerator_class_init (GFileEnumeratorClass *klass)
99 {
100   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
101   
102   g_type_class_add_private (klass, sizeof (GFileEnumeratorPrivate));
103   
104   gobject_class->finalize = g_file_enumerator_finalize;
105
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;
110 }
111
112 static void
113 g_file_enumerator_init (GFileEnumerator *enumerator)
114 {
115   enumerator->priv = G_TYPE_INSTANCE_GET_PRIVATE (enumerator,
116                                                   G_TYPE_FILE_ENUMERATOR,
117                                                   GFileEnumeratorPrivate);
118 }
119
120 /**
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
125  *
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.
130  *
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
133  * be unset.
134  *
135  * Return value: A #GFileInfo or %NULL on error or end of enumerator
136  **/
137 GFileInfo *
138 g_file_enumerator_next_file (GFileEnumerator *enumerator,
139                              GCancellable *cancellable,
140                              GError **error)
141 {
142   GFileEnumeratorClass *class;
143   GFileInfo *info;
144   
145   g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
146   g_return_val_if_fail (enumerator != NULL, NULL);
147   
148   if (enumerator->priv->closed)
149     {
150       g_set_error (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
151                    _("Enumerator is closed"));
152       return NULL;
153     }
154
155   if (enumerator->priv->pending)
156     {
157       g_set_error (error, G_IO_ERROR, G_IO_ERROR_PENDING,
158                    _("File enumerator has outstanding operation"));
159       return NULL;
160     }
161
162   if (enumerator->priv->outstanding_error)
163     {
164       g_propagate_error (error, enumerator->priv->outstanding_error);
165       enumerator->priv->outstanding_error = NULL;
166       return NULL;
167     }
168   
169   class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
170
171   if (cancellable)
172     g_cancellable_push_current (cancellable);
173   
174   enumerator->priv->pending = TRUE;
175   info = (* class->next_file) (enumerator, cancellable, error);
176   enumerator->priv->pending = FALSE;
177
178   if (cancellable)
179     g_cancellable_pop_current (cancellable);
180   
181   return info;
182 }
183   
184 /**
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
189  *
190  * Releases all resources used by this enumerator, making the
191  * enumerator return %G_IO_ERROR_CLOSED on all calls.
192  *
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.
196  *
197  * Return value: #TRUE on success or #FALSE on error.
198  **/
199 gboolean
200 g_file_enumerator_close (GFileEnumerator  *enumerator,
201                          GCancellable     *cancellable,
202                          GError          **error)
203 {
204   GFileEnumeratorClass *class;
205
206   g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
207   g_return_val_if_fail (enumerator != NULL, FALSE);
208   
209   class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
210
211   if (enumerator->priv->closed)
212     return TRUE;
213   
214   if (enumerator->priv->pending)
215     {
216       g_set_error (error, G_IO_ERROR, G_IO_ERROR_PENDING,
217                    _("File enumerator has outstanding operation"));
218       return FALSE;
219     }
220
221   if (cancellable)
222     g_cancellable_push_current (cancellable);
223   
224   enumerator->priv->pending = TRUE;
225   (* class->close_fn) (enumerator, cancellable, error);
226   enumerator->priv->pending = FALSE;
227   enumerator->priv->closed = TRUE;
228
229   if (cancellable)
230     g_cancellable_pop_current (cancellable);
231   
232   return TRUE;
233 }
234
235 static void
236 next_async_callback_wrapper (GObject      *source_object,
237                              GAsyncResult *res,
238                              gpointer      user_data)
239 {
240   GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
241
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);
246 }
247
248 /**
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> 
253  *     of the request. 
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
257  *
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. 
261  *
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.
267  *
268  * During an async request no other sync and async calls are allowed, and will
269  * result in %G_IO_ERROR_PENDING errors. 
270  *
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.
274  **/
275 void
276 g_file_enumerator_next_files_async (GFileEnumerator     *enumerator,
277                                     int                  num_files,
278                                     int                  io_priority,
279                                     GCancellable        *cancellable,
280                                     GAsyncReadyCallback  callback,
281                                     gpointer             user_data)
282 {
283   GFileEnumeratorClass *class;
284   GSimpleAsyncResult *simple;
285
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);
289
290   if (num_files == 0)
291     {
292       simple = g_simple_async_result_new (G_OBJECT (enumerator),
293                                           callback,
294                                           user_data,
295                                           g_file_enumerator_next_files_async);
296       g_simple_async_result_complete_in_idle (simple);
297       g_object_unref (simple);
298       return;
299     }
300   
301   if (enumerator->priv->closed)
302     {
303       g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
304                                            callback,
305                                            user_data,
306                                            G_IO_ERROR, G_IO_ERROR_CLOSED,
307                                            _("File enumerator is already closed"));
308       return;
309     }
310   
311   if (enumerator->priv->pending)
312     {
313       g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
314                                            callback,
315                                            user_data,
316                                            G_IO_ERROR, G_IO_ERROR_PENDING,
317                                            _("File enumerator has outstanding operation"));
318       return;
319     }
320
321   class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
322   
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);
328 }
329
330 /**
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 
335  * ignore.
336  * 
337  * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
338  * 
339  * Returns: a #GList of #GFileInfo<!---->s.
340  **/
341 GList *
342 g_file_enumerator_next_files_finish (GFileEnumerator  *enumerator,
343                                      GAsyncResult     *result,
344                                      GError          **error)
345 {
346   GFileEnumeratorClass *class;
347   GSimpleAsyncResult *simple;
348   
349   g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
350   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
351   
352   if (G_IS_SIMPLE_ASYNC_RESULT (result))
353     {
354       simple = G_SIMPLE_ASYNC_RESULT (result);
355       if (g_simple_async_result_propagate_error (simple, error))
356         return NULL;
357       
358       /* Special case read of 0 files */
359       if (g_simple_async_result_get_source_tag (simple) == g_file_enumerator_next_files_async)
360         return NULL;
361     }
362   
363   class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
364   return class->next_files_finish (enumerator, result, error);
365 }
366
367 static void
368 close_async_callback_wrapper (GObject      *source_object,
369                               GAsyncResult *res,
370                               gpointer      user_data)
371 {
372   GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
373   
374   enumerator->priv->pending = FALSE;
375   enumerator->priv->closed = TRUE;
376   if (enumerator->priv->outstanding_callback)
377     (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
378   g_object_unref (enumerator);
379 }
380
381 /**
382  * g_file_enumerator_close_async:
383  * @enumerator: a #GFileEnumerator.
384  * @io_priority: the <link linkend="io-priority">I/O priority</link> 
385  *     of the request.
386  * @cancellable: optional #GCancellable object, %NULL to ignore. 
387  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
388  * @user_data: the data to pass to callback function
389  *
390  * Asynchronously closes the file enumerator. 
391  *
392  * If @cancellable is not %NULL, then the operation can be cancelled by
393  * triggering the cancellable object from another thread. If the operation
394  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in 
395  * g_file_enumerator_close_finish(). 
396  **/
397 void
398 g_file_enumerator_close_async (GFileEnumerator     *enumerator,
399                                int                  io_priority,
400                                GCancellable        *cancellable,
401                                GAsyncReadyCallback  callback,
402                                gpointer             user_data)
403 {
404   GFileEnumeratorClass *class;
405
406   g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
407
408   if (enumerator->priv->closed)
409     {
410       g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
411                                            callback,
412                                            user_data,
413                                            G_IO_ERROR, G_IO_ERROR_CLOSED,
414                                            _("File enumerator is already closed"));
415       return;
416     }
417   
418   if (enumerator->priv->pending)
419     {
420       g_simple_async_report_error_in_idle (G_OBJECT (enumerator),
421                                            callback,
422                                            user_data,
423                                            G_IO_ERROR, G_IO_ERROR_PENDING,
424                                            _("File enumerator has outstanding operation"));
425       return;
426     }
427
428   class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
429   
430   enumerator->priv->pending = TRUE;
431   enumerator->priv->outstanding_callback = callback;
432   g_object_ref (enumerator);
433   (* class->close_async) (enumerator, io_priority, cancellable,
434                           close_async_callback_wrapper, user_data);
435 }
436
437 /**
438  * g_file_enumerator_close_finish:
439  * @enumerator: a #GFileEnumerator.
440  * @result: a #GAsyncResult.
441  * @error: a #GError location to store the error occuring, or %NULL to 
442  * ignore.
443  * 
444  * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
445  * 
446  * If the file enumerator was already closed when g_file_enumerator_close_async() 
447  * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and 
448  * return %FALSE. If the file enumerator had pending operation when the close 
449  * operation was started, then this function will report %G_IO_ERROR_PENDING, and
450  * return %FALSE.  If @cancellable was not %NULL, then the operation may have been 
451  * cancelled by triggering the cancellable object from another thread. If the operation
452  * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be 
453  * returned. 
454  * 
455  * Returns: %TRUE if the close operation has finished successfully.
456  **/
457 gboolean
458 g_file_enumerator_close_finish (GFileEnumerator  *enumerator,
459                                 GAsyncResult     *result,
460                                 GError          **error)
461 {
462   GSimpleAsyncResult *simple;
463   GFileEnumeratorClass *class;
464
465   g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
466   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
467   
468   if (G_IS_SIMPLE_ASYNC_RESULT (result))
469     {
470       simple = G_SIMPLE_ASYNC_RESULT (result);
471       if (g_simple_async_result_propagate_error (simple, error))
472         return FALSE;
473     }
474   
475   class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
476   return class->close_finish (enumerator, result, error);
477 }
478
479 /**
480  * g_file_enumerator_is_closed:
481  * @enumerator: a #GFileEnumerator.
482  *
483  * Checks if the file enumerator has been closed.
484  * 
485  * Returns: %TRUE if the @enumerator is closed.
486  **/
487 gboolean
488 g_file_enumerator_is_closed (GFileEnumerator *enumerator)
489 {
490   g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
491   
492   return enumerator->priv->closed;
493 }
494
495 /**
496  * g_file_enumerator_has_pending:
497  * @enumerator: a #GFileEnumerator.
498  * 
499  * Checks if the file enumerator has pending operations.
500  *
501  * Returns: %TRUE if the @enumerator has pending operations.
502  **/
503 gboolean
504 g_file_enumerator_has_pending (GFileEnumerator *enumerator)
505 {
506   g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
507   
508   return enumerator->priv->pending;
509 }
510
511 /**
512  * g_file_enumerator_set_pending:
513  * @enumerator: a #GFileEnumerator.
514  * @pending: a boolean value.
515  * 
516  * Sets the file enumerator as having pending operations.
517  **/
518 void
519 g_file_enumerator_set_pending (GFileEnumerator *enumerator,
520                                gboolean         pending)
521 {
522   g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
523   
524   enumerator->priv->pending = pending;
525 }
526
527 typedef struct {
528   int                num_files;
529   GList             *files;
530 } NextAsyncOp;
531
532 static void
533 next_files_thread (GSimpleAsyncResult *res,
534                    GObject            *object,
535                    GCancellable       *cancellable)
536 {
537   NextAsyncOp *op;
538   GFileEnumeratorClass *class;
539   GError *error = NULL;
540   GFileInfo *info;
541   GFileEnumerator *enumerator;
542   int i;
543
544   enumerator = G_FILE_ENUMERATOR (object);
545   op = g_simple_async_result_get_op_res_gpointer (res);
546
547   class = G_FILE_ENUMERATOR_GET_CLASS (object);
548
549   for (i = 0; i < op->num_files; i++)
550     {
551       if (g_cancellable_set_error_if_cancelled (cancellable, &error))
552         info = NULL;
553       else
554         info = class->next_file (enumerator, cancellable, &error);
555       
556       if (info == NULL)
557         {
558           /* If we get an error after first file, return that on next operation */
559           if (error != NULL && i > 0)
560             {
561               if (error->domain == G_IO_ERROR &&
562                   error->code == G_IO_ERROR_CANCELLED)
563                 g_error_free (error); /* Never propagate cancel errors to other call */
564               else
565                 enumerator->priv->outstanding_error = error;
566               error = NULL;
567             }
568               
569           break;
570         }
571       else
572         op->files = g_list_prepend (op->files, info);
573     }
574 }
575
576
577 static void
578 g_file_enumerator_real_next_files_async (GFileEnumerator     *enumerator,
579                                          int                  num_files,
580                                          int                  io_priority,
581                                          GCancellable        *cancellable,
582                                          GAsyncReadyCallback  callback,
583                                          gpointer             user_data)
584 {
585   GSimpleAsyncResult *res;
586   NextAsyncOp *op;
587
588   op = g_new0 (NextAsyncOp, 1);
589
590   op->num_files = num_files;
591   op->files = NULL;
592
593   res = g_simple_async_result_new (G_OBJECT (enumerator), callback, user_data, g_file_enumerator_real_next_files_async);
594   g_simple_async_result_set_op_res_gpointer (res, op, g_free);
595   
596   g_simple_async_result_run_in_thread (res, next_files_thread, io_priority, cancellable);
597   g_object_unref (res);
598 }
599
600 static GList *
601 g_file_enumerator_real_next_files_finish (GFileEnumerator                *enumerator,
602                                           GAsyncResult                   *result,
603                                           GError                        **error)
604 {
605   GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
606   NextAsyncOp *op;
607
608   g_warn_if_fail (g_simple_async_result_get_source_tag (simple) == 
609             g_file_enumerator_real_next_files_async);
610
611   op = g_simple_async_result_get_op_res_gpointer (simple);
612
613   return op->files;
614 }
615
616 static void
617 close_async_thread (GSimpleAsyncResult *res,
618                     GObject            *object,
619                     GCancellable       *cancellable)
620 {
621   GFileEnumeratorClass *class;
622   GError *error = NULL;
623   gboolean result;
624
625   /* Auto handling of cancelation disabled, and ignore
626      cancellation, since we want to close things anyway, although
627      possibly in a quick-n-dirty way. At least we never want to leak
628      open handles */
629   
630   class = G_FILE_ENUMERATOR_GET_CLASS (object);
631   result = class->close_fn (G_FILE_ENUMERATOR (object), cancellable, &error);
632   if (!result)
633     {
634       g_simple_async_result_set_from_error (res, error);
635       g_error_free (error);
636     }
637 }
638
639
640 static void
641 g_file_enumerator_real_close_async (GFileEnumerator     *enumerator,
642                                     int                  io_priority,
643                                     GCancellable        *cancellable,
644                                     GAsyncReadyCallback  callback,
645                                     gpointer             user_data)
646 {
647   GSimpleAsyncResult *res;
648   
649   res = g_simple_async_result_new (G_OBJECT (enumerator),
650                                    callback,
651                                    user_data,
652                                    g_file_enumerator_real_close_async);
653
654   g_simple_async_result_set_handle_cancellation (res, FALSE);
655   
656   g_simple_async_result_run_in_thread (res,
657                                        close_async_thread,
658                                        io_priority,
659                                        cancellable);
660   g_object_unref (res);
661 }
662
663 static gboolean
664 g_file_enumerator_real_close_finish (GFileEnumerator  *enumerator,
665                                      GAsyncResult     *result,
666                                      GError          **error)
667 {
668   GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
669   g_warn_if_fail (g_simple_async_result_get_source_tag (simple) == 
670             g_file_enumerator_real_close_async);
671   return TRUE;
672 }
673
674 #define __G_FILE_ENUMERATOR_C__
675 #include "gioaliasdef.c"