Branch data Line data Source code
1 : : /* GIO - GLib Input, Output and Streaming Library
2 : : *
3 : : * Copyright (C) 2006-2007 Red Hat, Inc.
4 : : *
5 : : * SPDX-License-Identifier: LGPL-2.1-or-later
6 : : *
7 : : * This library is free software; you can redistribute it and/or
8 : : * modify it under the terms of the GNU Lesser General Public
9 : : * License as published by the Free Software Foundation; either
10 : : * version 2.1 of the License, or (at your option) any later version.
11 : : *
12 : : * This library is distributed in the hope that it will be useful,
13 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 : : * Lesser General Public License for more details.
16 : : *
17 : : * You should have received a copy of the GNU Lesser General
18 : : * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 : : *
20 : : * Author: Alexander Larsson <alexl@redhat.com>
21 : : */
22 : :
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 "gioerror.h"
30 : : #include "glibintl.h"
31 : :
32 : : struct _GFileEnumeratorPrivate {
33 : : /* TODO: Should be public for subclasses? */
34 : : GFile *container;
35 : : guint closed : 1;
36 : : guint pending : 1;
37 : : GAsyncReadyCallback outstanding_callback;
38 : : GError *outstanding_error;
39 : : };
40 : :
41 : : /**
42 : : * GFileEnumerator:
43 : : *
44 : : * `GFileEnumerator` allows you to operate on a set of [iface@Gio.File] objects,
45 : : * returning a [class@Gio.FileInfo] structure for each file enumerated (e.g.
46 : : * [method@Gio.File.enumerate_children] will return a `GFileEnumerator` for each
47 : : * of the children within a directory).
48 : : *
49 : : * To get the next file's information from a `GFileEnumerator`, use
50 : : * [method@Gio.FileEnumerator.next_file] or its asynchronous version,
51 : : * [method@Gio.FileEnumerator.next_files_async]. Note that the asynchronous
52 : : * version will return a list of [class@Gio.FileInfo] objects, whereas the
53 : : * synchronous will only return the next file in the enumerator.
54 : : *
55 : : * The ordering of returned files is unspecified for non-Unix
56 : : * platforms; for more information, see [method@GLib.Dir.read_name]. On Unix,
57 : : * when operating on local files, returned files will be sorted by
58 : : * inode number. Effectively you can assume that the ordering of
59 : : * returned files will be stable between successive calls (and
60 : : * applications) assuming the directory is unchanged.
61 : : *
62 : : * If your application needs a specific ordering, such as by name or
63 : : * modification time, you will have to implement that in your
64 : : * application code.
65 : : *
66 : : * To close a `GFileEnumerator`, use [method@Gio.FileEnumerator.close], or
67 : : * its asynchronous version, [method@Gio.FileEnumerator.close_async]. Once
68 : : * a `GFileEnumerator` is closed, no further actions may be performed
69 : : * on it, and it should be freed with [method@GObject.Object.unref].
70 : : *
71 : : **/
72 : :
73 : 2136 : G_DEFINE_TYPE_WITH_PRIVATE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT)
74 : :
75 : : enum {
76 : : PROP_0,
77 : : PROP_CONTAINER
78 : : };
79 : :
80 : : static void g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
81 : : int num_files,
82 : : int io_priority,
83 : : GCancellable *cancellable,
84 : : GAsyncReadyCallback callback,
85 : : gpointer user_data);
86 : : static GList * g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
87 : : GAsyncResult *res,
88 : : GError **error);
89 : : static void g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
90 : : int io_priority,
91 : : GCancellable *cancellable,
92 : : GAsyncReadyCallback callback,
93 : : gpointer user_data);
94 : : static gboolean g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
95 : : GAsyncResult *res,
96 : : GError **error);
97 : :
98 : : static void
99 : 244 : g_file_enumerator_set_property (GObject *object,
100 : : guint property_id,
101 : : const GValue *value,
102 : : GParamSpec *pspec)
103 : : {
104 : : GFileEnumerator *enumerator;
105 : :
106 : 244 : enumerator = G_FILE_ENUMERATOR (object);
107 : :
108 : 244 : switch (property_id) {
109 : 236 : case PROP_CONTAINER:
110 : 244 : enumerator->priv->container = g_value_dup_object (value);
111 : 244 : break;
112 : 0 : default:
113 : 0 : G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
114 : 0 : break;
115 : : }
116 : 244 : }
117 : :
118 : : static void
119 : 246 : g_file_enumerator_dispose (GObject *object)
120 : : {
121 : : GFileEnumerator *enumerator;
122 : :
123 : 246 : enumerator = G_FILE_ENUMERATOR (object);
124 : :
125 : 246 : if (enumerator->priv->container) {
126 : 242 : g_object_unref (enumerator->priv->container);
127 : 242 : enumerator->priv->container = NULL;
128 : 7 : }
129 : :
130 : 246 : if (!enumerator->priv->closed)
131 : 207 : g_file_enumerator_close (enumerator, NULL, NULL);
132 : :
133 : 246 : G_OBJECT_CLASS (g_file_enumerator_parent_class)->dispose (object);
134 : 246 : }
135 : :
136 : : static void
137 : 11 : g_file_enumerator_class_init (GFileEnumeratorClass *klass)
138 : : {
139 : 11 : GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
140 : :
141 : 11 : gobject_class->set_property = g_file_enumerator_set_property;
142 : 11 : gobject_class->dispose = g_file_enumerator_dispose;
143 : :
144 : 11 : klass->next_files_async = g_file_enumerator_real_next_files_async;
145 : 11 : klass->next_files_finish = g_file_enumerator_real_next_files_finish;
146 : 11 : klass->close_async = g_file_enumerator_real_close_async;
147 : 11 : klass->close_finish = g_file_enumerator_real_close_finish;
148 : :
149 : : /**
150 : : * GFileEnumerator:container:
151 : : *
152 : : * The container that is being enumerated.
153 : : */
154 : 11 : g_object_class_install_property
155 : 4 : (gobject_class, PROP_CONTAINER,
156 : 4 : g_param_spec_object ("container", NULL, NULL,
157 : 4 : G_TYPE_FILE,
158 : : G_PARAM_WRITABLE |
159 : : G_PARAM_CONSTRUCT_ONLY |
160 : : G_PARAM_STATIC_STRINGS));
161 : 11 : }
162 : :
163 : : static void
164 : 244 : g_file_enumerator_init (GFileEnumerator *enumerator)
165 : : {
166 : 244 : enumerator->priv = g_file_enumerator_get_instance_private (enumerator);
167 : 244 : }
168 : :
169 : : /**
170 : : * g_file_enumerator_next_file:
171 : : * @enumerator: a file enumerator
172 : : * @cancellable: (nullable): optional cancellable object
173 : : * @error: return location for an error, or `NULL`
174 : : *
175 : : * Returns information for the next file in the enumerated object.
176 : : *
177 : : * Will block until the information is available. The [class@Gio.FileInfo]
178 : : * returned from this function will contain attributes that match the
179 : : * attribute string that was passed when the file enumerator was created.
180 : : *
181 : : * See the documentation of [class@Gio.FileEnumerator] for information about the
182 : : * order of returned files.
183 : : *
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.
187 : : *
188 : : * Returns: (nullable) (transfer full): A file info object, or `NULL` on error
189 : : * or end of enumerator
190 : : **/
191 : : GFileInfo *
192 : 597 : g_file_enumerator_next_file (GFileEnumerator *enumerator,
193 : : GCancellable *cancellable,
194 : : GError **error)
195 : : {
196 : : GFileEnumeratorClass *class;
197 : : GFileInfo *info;
198 : :
199 : 600 : g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
200 : 597 : g_return_val_if_fail (enumerator != NULL, NULL);
201 : :
202 : 597 : if (enumerator->priv->closed)
203 : : {
204 : 0 : g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_CLOSED,
205 : 0 : _("Enumerator is closed"));
206 : 0 : return NULL;
207 : : }
208 : :
209 : 597 : if (enumerator->priv->pending)
210 : : {
211 : 0 : g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
212 : 0 : _("File enumerator has outstanding operation"));
213 : 0 : return NULL;
214 : : }
215 : :
216 : 597 : if (enumerator->priv->outstanding_error)
217 : : {
218 : 0 : g_propagate_error (error, enumerator->priv->outstanding_error);
219 : 0 : enumerator->priv->outstanding_error = NULL;
220 : 0 : return NULL;
221 : : }
222 : :
223 : 597 : class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
224 : :
225 : 597 : if (cancellable)
226 : 1 : g_cancellable_push_current (cancellable);
227 : :
228 : 597 : enumerator->priv->pending = TRUE;
229 : 597 : info = (* class->next_file) (enumerator, cancellable, error);
230 : 597 : enumerator->priv->pending = FALSE;
231 : :
232 : 597 : if (cancellable)
233 : 1 : g_cancellable_pop_current (cancellable);
234 : :
235 : 597 : return info;
236 : 3 : }
237 : :
238 : : /**
239 : : * g_file_enumerator_close:
240 : : * @enumerator: a file enumerator
241 : : * @cancellable: (nullable): optional cancellable object
242 : : * @error: return location for an error, or `NULL`
243 : : *
244 : : * Releases all resources used by this enumerator.
245 : : *
246 : : * The enumerator will return [error@Gio.IOErrorEnum.CLOSED] on all subsequent
247 : : * calls.
248 : : *
249 : : * This will be automatically called when the last reference
250 : : * is dropped, but you might want to call this function to make
251 : : * sure resources are released as early as possible.
252 : : *
253 : : * Returns: true on success; false otherwise
254 : : **/
255 : : gboolean
256 : 232 : g_file_enumerator_close (GFileEnumerator *enumerator,
257 : : GCancellable *cancellable,
258 : : GError **error)
259 : : {
260 : : GFileEnumeratorClass *class;
261 : :
262 : 234 : g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
263 : 232 : g_return_val_if_fail (enumerator != NULL, FALSE);
264 : :
265 : 232 : class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
266 : :
267 : 232 : if (enumerator->priv->closed)
268 : 0 : return TRUE;
269 : :
270 : 232 : if (enumerator->priv->pending)
271 : : {
272 : 0 : g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_PENDING,
273 : 0 : _("File enumerator has outstanding operation"));
274 : 0 : return FALSE;
275 : : }
276 : :
277 : 232 : if (cancellable)
278 : 0 : g_cancellable_push_current (cancellable);
279 : :
280 : 232 : enumerator->priv->pending = TRUE;
281 : 232 : (* class->close_fn) (enumerator, cancellable, error);
282 : 232 : enumerator->priv->pending = FALSE;
283 : 232 : enumerator->priv->closed = TRUE;
284 : :
285 : 232 : if (cancellable)
286 : 0 : g_cancellable_pop_current (cancellable);
287 : :
288 : 232 : return TRUE;
289 : 2 : }
290 : :
291 : : static void
292 : 24 : next_async_callback_wrapper (GObject *source_object,
293 : : GAsyncResult *res,
294 : : gpointer user_data)
295 : : {
296 : 24 : GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
297 : :
298 : 24 : enumerator->priv->pending = FALSE;
299 : 24 : if (enumerator->priv->outstanding_callback)
300 : 24 : (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
301 : 24 : g_object_unref (enumerator);
302 : 24 : }
303 : :
304 : : /**
305 : : * g_file_enumerator_next_files_async:
306 : : * @enumerator: a file enumerator
307 : : * @num_files: the number of file info objects to request
308 : : * @io_priority: the [I/O priority](iface.AsyncResult.html#io-priority) of the
309 : : * request
310 : : * @cancellable: (nullable): optional cancellable object
311 : : * @callback: (scope async) (closure user_data): callback to call when the
312 : : * request is satisfied
313 : : * @user_data: the data to pass to @callback
314 : : *
315 : : * Request information for a number of files from the enumerator asynchronously.
316 : : *
317 : : * When all I/O for the operation is finished the @callback will be called with
318 : : * the requested information.
319 : : *
320 : : * See the documentation of [class@Gio.FileEnumerator] for information about the
321 : : * order of returned files.
322 : : *
323 : : * Once the end of the enumerator is reached, or if an error occurs, the
324 : : * @callback will be called with an empty list. In this case, the previous call
325 : : * to [method@Gio.FileEnumerator.next_files_async] will typically have returned
326 : : * fewer than @num_files items.
327 : : *
328 : : * If a request is cancelled the callback will be called with
329 : : * [error@Gio.IOErrorEnum.CANCELLED].
330 : : *
331 : : * This leads to the following pseudo-code usage:
332 : : * ```c
333 : : * g_autoptr(GFile) dir = get_directory ();
334 : : * g_autoptr(GFileEnumerator) enumerator = NULL;
335 : : * g_autolist(GFileInfo) files = NULL;
336 : : * g_autoptr(GError) local_error = NULL;
337 : : *
338 : : * enumerator = yield g_file_enumerate_children_async (dir,
339 : : * G_FILE_ATTRIBUTE_STANDARD_NAME ","
340 : : * G_FILE_ATTRIBUTE_STANDARD_TYPE,
341 : : * G_FILE_QUERY_INFO_NONE,
342 : : * G_PRIORITY_DEFAULT,
343 : : * cancellable,
344 : : * …,
345 : : * &local_error);
346 : : * if (enumerator == NULL)
347 : : * g_error ("Error enumerating: %s", local_error->message);
348 : : *
349 : : * // Loop until no files are returned, either because the end of the enumerator
350 : : * // has been reached, or an error was returned.
351 : : * do
352 : : * {
353 : : * files = yield g_file_enumerator_next_files_async (enumerator,
354 : : * 5, // number of files to request
355 : : * G_PRIORITY_DEFAULT,
356 : : * cancellable,
357 : : * …,
358 : : * &local_error);
359 : : *
360 : : * // Process the returned files, but don’t assume that exactly 5 were returned.
361 : : * for (GList *l = files; l != NULL; l = l->next)
362 : : * {
363 : : * GFileInfo *info = l->data;
364 : : * handle_file_info (info);
365 : : * }
366 : : * }
367 : : * while (files != NULL);
368 : : *
369 : : * if (local_error != NULL &&
370 : : * !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
371 : : * g_error ("Error while enumerating: %s", local_error->message);
372 : : * ```
373 : : *
374 : : * During an async request no other sync and async calls are allowed, and will
375 : : * result in [error@Gio.IOErrorEnum.PENDING] errors.
376 : : *
377 : : * Any outstanding I/O request with higher priority (lower numerical value) will
378 : : * be executed before an outstanding request with lower priority. Default
379 : : * priority is [const@GLib.PRIORITY_DEFAULT].
380 : : **/
381 : : void
382 : 24 : g_file_enumerator_next_files_async (GFileEnumerator *enumerator,
383 : : int num_files,
384 : : int io_priority,
385 : : GCancellable *cancellable,
386 : : GAsyncReadyCallback callback,
387 : : gpointer user_data)
388 : : {
389 : : GFileEnumeratorClass *class;
390 : :
391 : 36 : g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
392 : 24 : g_return_if_fail (enumerator != NULL);
393 : 24 : g_return_if_fail (num_files >= 0);
394 : :
395 : 24 : if (num_files == 0)
396 : : {
397 : : GTask *task;
398 : :
399 : 0 : task = g_task_new (enumerator, cancellable, callback, user_data);
400 : 0 : g_task_set_source_tag (task, g_file_enumerator_next_files_async);
401 : 0 : g_task_return_pointer (task, NULL, NULL);
402 : 0 : g_object_unref (task);
403 : 0 : return;
404 : : }
405 : :
406 : 24 : if (enumerator->priv->closed)
407 : : {
408 : 0 : g_task_report_new_error (enumerator, callback, user_data,
409 : : g_file_enumerator_next_files_async,
410 : 0 : G_IO_ERROR, G_IO_ERROR_CLOSED,
411 : 0 : _("File enumerator is already closed"));
412 : 0 : return;
413 : : }
414 : :
415 : 24 : if (enumerator->priv->pending)
416 : : {
417 : 0 : g_task_report_new_error (enumerator, callback, user_data,
418 : : g_file_enumerator_next_files_async,
419 : 0 : G_IO_ERROR, G_IO_ERROR_PENDING,
420 : 0 : _("File enumerator has outstanding operation"));
421 : 0 : return;
422 : : }
423 : :
424 : 24 : class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
425 : :
426 : 24 : enumerator->priv->pending = TRUE;
427 : 24 : enumerator->priv->outstanding_callback = callback;
428 : 24 : g_object_ref (enumerator);
429 : 36 : (* class->next_files_async) (enumerator, num_files, io_priority, cancellable,
430 : 12 : next_async_callback_wrapper, user_data);
431 : 12 : }
432 : :
433 : : /**
434 : : * g_file_enumerator_next_files_finish:
435 : : * @enumerator: a file enumerator
436 : : * @result: an async result
437 : : * @error: return location for an error, or `NULL`
438 : : *
439 : : * Finishes the asynchronous operation started with
440 : : * [method@Gio.FileEnumerator.next_files_async()].
441 : : *
442 : : * Returns: (transfer full) (element-type Gio.FileInfo): a list of file info
443 : : * objects
444 : : **/
445 : : GList *
446 : 24 : g_file_enumerator_next_files_finish (GFileEnumerator *enumerator,
447 : : GAsyncResult *result,
448 : : GError **error)
449 : : {
450 : : GFileEnumeratorClass *class;
451 : :
452 : 36 : g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
453 : 36 : g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
454 : :
455 : 24 : if (g_async_result_legacy_propagate_error (result, error))
456 : 0 : return NULL;
457 : 24 : else if (g_async_result_is_tagged (result, g_file_enumerator_next_files_async))
458 : 0 : return g_task_propagate_pointer (G_TASK (result), error);
459 : :
460 : 24 : class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
461 : 24 : return class->next_files_finish (enumerator, result, error);
462 : 12 : }
463 : :
464 : : static void
465 : 10 : close_async_callback_wrapper (GObject *source_object,
466 : : GAsyncResult *res,
467 : : gpointer user_data)
468 : : {
469 : 10 : GFileEnumerator *enumerator = G_FILE_ENUMERATOR (source_object);
470 : :
471 : 10 : enumerator->priv->pending = FALSE;
472 : 10 : enumerator->priv->closed = TRUE;
473 : 10 : if (enumerator->priv->outstanding_callback)
474 : 0 : (*enumerator->priv->outstanding_callback) (source_object, res, user_data);
475 : 10 : g_object_unref (enumerator);
476 : 10 : }
477 : :
478 : : /**
479 : : * g_file_enumerator_close_async:
480 : : * @enumerator: a file enumerator
481 : : * @io_priority: the [I/O priority](iface.AsyncResult.html#io-priority) of the
482 : : * request
483 : : * @cancellable: (nullable): optional cancellable object
484 : : * @callback: (scope async) (closure user_data): a callback to call when the
485 : : * request is satisfied
486 : : * @user_data: the data to pass to @callback
487 : : *
488 : : * Asynchronously closes the file enumerator.
489 : : *
490 : : * If @cancellable is not `NULL`, then the operation can be cancelled by
491 : : * triggering the cancellable object from another thread. If the operation
492 : : * was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be returned
493 : : * by [method@Gio.FileEnumerator.close_finish()].
494 : : **/
495 : : void
496 : 12 : g_file_enumerator_close_async (GFileEnumerator *enumerator,
497 : : int io_priority,
498 : : GCancellable *cancellable,
499 : : GAsyncReadyCallback callback,
500 : : gpointer user_data)
501 : : {
502 : : GFileEnumeratorClass *class;
503 : :
504 : 18 : g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
505 : :
506 : 12 : if (enumerator->priv->closed)
507 : : {
508 : 0 : g_task_report_new_error (enumerator, callback, user_data,
509 : : g_file_enumerator_close_async,
510 : 0 : G_IO_ERROR, G_IO_ERROR_CLOSED,
511 : 0 : _("File enumerator is already closed"));
512 : 0 : return;
513 : : }
514 : :
515 : 12 : if (enumerator->priv->pending)
516 : : {
517 : 0 : g_task_report_new_error (enumerator, callback, user_data,
518 : : g_file_enumerator_close_async,
519 : 0 : G_IO_ERROR, G_IO_ERROR_PENDING,
520 : 0 : _("File enumerator has outstanding operation"));
521 : 0 : return;
522 : : }
523 : :
524 : 12 : class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
525 : :
526 : 12 : enumerator->priv->pending = TRUE;
527 : 12 : enumerator->priv->outstanding_callback = callback;
528 : 12 : g_object_ref (enumerator);
529 : 18 : (* class->close_async) (enumerator, io_priority, cancellable,
530 : 6 : close_async_callback_wrapper, user_data);
531 : 6 : }
532 : :
533 : : /**
534 : : * g_file_enumerator_close_finish:
535 : : * @enumerator: a file enumerator
536 : : * @result: an async result
537 : : * @error: return location for an error, or `NULL`
538 : : *
539 : : * Finishes closing a file enumerator, started by
540 : : * [method@Gio.FileEnumerator.close_async].
541 : : *
542 : : * If the file enumerator was already closed when
543 : : * [method@Gio.FileEnumerator.close_async] was called, then this function will
544 : : * report [error@Gio.IOErrorEnum.CLOSED] in @error. If the file enumerator had a
545 : : * pending operation when the close operation was started, then
546 : : * [error@Gio.IOErrorEnum.PENDING] will be reported. If the operation was
547 : : * cancelled from another thread using @cancellable,
548 : : * [error@Gio.IOErrorEnum.CANCELLED] will be reported.
549 : : *
550 : : * Returns: true on success; false otherwise
551 : : **/
552 : : gboolean
553 : 0 : g_file_enumerator_close_finish (GFileEnumerator *enumerator,
554 : : GAsyncResult *result,
555 : : GError **error)
556 : : {
557 : : GFileEnumeratorClass *class;
558 : :
559 : 0 : g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), FALSE);
560 : 0 : g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
561 : :
562 : 0 : if (g_async_result_legacy_propagate_error (result, error))
563 : 0 : return FALSE;
564 : 0 : else if (g_async_result_is_tagged (result, g_file_enumerator_close_async))
565 : 0 : return g_task_propagate_boolean (G_TASK (result), error);
566 : :
567 : 0 : class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
568 : 0 : return class->close_finish (enumerator, result, error);
569 : 0 : }
570 : :
571 : : /**
572 : : * g_file_enumerator_is_closed:
573 : : * @enumerator: a file enumerator
574 : : *
575 : : * Checks if the file enumerator has been closed.
576 : : *
577 : : * Returns: true if the @enumerator is closed
578 : : **/
579 : : gboolean
580 : 9 : g_file_enumerator_is_closed (GFileEnumerator *enumerator)
581 : : {
582 : 9 : g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
583 : :
584 : 9 : return enumerator->priv->closed;
585 : 0 : }
586 : :
587 : : /**
588 : : * g_file_enumerator_has_pending:
589 : : * @enumerator: a file enumerator
590 : : *
591 : : * Checks if the file enumerator has pending operations.
592 : : *
593 : : * Returns: true if the @enumerator has pending operations
594 : : **/
595 : : gboolean
596 : 0 : g_file_enumerator_has_pending (GFileEnumerator *enumerator)
597 : : {
598 : 0 : g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), TRUE);
599 : :
600 : 0 : return enumerator->priv->pending;
601 : 0 : }
602 : :
603 : : /**
604 : : * g_file_enumerator_set_pending:
605 : : * @enumerator: a file enumerator
606 : : * @pending: a boolean value
607 : : *
608 : : * Sets the file enumerator as having pending operations.
609 : : **/
610 : : void
611 : 0 : g_file_enumerator_set_pending (GFileEnumerator *enumerator,
612 : : gboolean pending)
613 : : {
614 : 0 : g_return_if_fail (G_IS_FILE_ENUMERATOR (enumerator));
615 : :
616 : 0 : enumerator->priv->pending = pending;
617 : 0 : }
618 : :
619 : : /**
620 : : * g_file_enumerator_iterate:
621 : : * @direnum: an open file enumerator
622 : : * @out_info: (out) (transfer none) (optional): return location for the next
623 : : * file info object, or `NULL`
624 : : * @out_child: (out) (transfer none) (optional): return location for the next
625 : : * file object, or `NULL`
626 : : * @cancellable: (nullable): optional cancellable object
627 : : * @error: return location for an error, or `NULL`
628 : : *
629 : : * A version of [method@Gio.FileEnumerator.next_file] that’s easier to use
630 : : * correctly from C programs.
631 : : *
632 : : * With [method@Gio.FileEnumerator.next_file], the boolean return value
633 : : * signifies “end of iteration or error”, which requires allocation of a
634 : : * temporary [type@GLib.Error] to distinguish which one.
635 : : *
636 : : * In contrast, with this function, a false return from
637 : : * [method@Gio.FileEnumerator.iterate] *always* means “error”. End of iteration
638 : : * is signaled by @out_info or @out_child being `NULL`.
639 : : *
640 : : * Another crucial difference is that the references for @out_info and
641 : : * @out_child are owned by @direnum (they are cached as hidden
642 : : * properties). You must not unref them in your own code. This makes
643 : : * memory management significantly easier for C code in combination
644 : : * with loops.
645 : : *
646 : : * Finally, this function optionally allows retrieving a corresponding
647 : : * [iface@Gio.File] as well as each [class@Gio.FileInfo].
648 : : *
649 : : * To use this, [const@Gio.FILE_ATTRIBUTE_STANDARD_NAME] must have been listed
650 : : * in the attributes list used when creating the [class@Gio.FileEnumerator].
651 : : *
652 : : * You must specify at least one of @out_info or @out_child.
653 : : *
654 : : * The code pattern for correctly using [method@Gio.FileEnumerator.iterate] from
655 : : * C is:
656 : : *
657 : : * ```c
658 : : * direnum = g_file_enumerate_children (file, ...);
659 : : * while (TRUE)
660 : : * {
661 : : * GFileInfo *info = NULL;
662 : : *
663 : : * if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
664 : : * goto out;
665 : : *
666 : : * if (info == NULL)
667 : : * break;
668 : : *
669 : : * // do stuff with "info"; do not unref it! ...
670 : : * }
671 : : *
672 : : * out:
673 : : * g_object_unref (direnum); // Note: frees the last @info
674 : : * ```
675 : : *
676 : : * Returns: true on success or “end of iteration”; false on error
677 : : * Since: 2.44
678 : : */
679 : : gboolean
680 : 316 : g_file_enumerator_iterate (GFileEnumerator *direnum,
681 : : GFileInfo **out_info,
682 : : GFile **out_child,
683 : : GCancellable *cancellable,
684 : : GError **error)
685 : : {
686 : 316 : gboolean ret = FALSE;
687 : 316 : GError *temp_error = NULL;
688 : 316 : GFileInfo *ret_info = NULL;
689 : :
690 : : static GQuark cached_info_quark;
691 : : static GQuark cached_child_quark;
692 : : static gsize quarks_initialized;
693 : :
694 : 316 : g_return_val_if_fail (direnum != NULL, FALSE);
695 : 316 : g_return_val_if_fail (out_info != NULL || out_child != NULL, FALSE);
696 : :
697 : 316 : if (g_once_init_enter (&quarks_initialized))
698 : : {
699 : 1 : cached_info_quark = g_quark_from_static_string ("g-cached-info");
700 : 1 : cached_child_quark = g_quark_from_static_string ("g-cached-child");
701 : 1 : g_once_init_leave (&quarks_initialized, 1);
702 : 0 : }
703 : :
704 : 316 : ret_info = g_file_enumerator_next_file (direnum, cancellable, &temp_error);
705 : 316 : if (temp_error != NULL)
706 : : {
707 : 0 : g_propagate_error (error, temp_error);
708 : 0 : goto out;
709 : : }
710 : :
711 : 316 : if (ret_info)
712 : : {
713 : 210 : if (out_child != NULL)
714 : : {
715 : 2 : const char *name = g_file_info_get_name (ret_info);
716 : :
717 : 2 : if (G_UNLIKELY (name == NULL))
718 : : {
719 : 0 : g_critical ("g_file_enumerator_iterate() created without standard::name");
720 : : g_return_val_if_reached (FALSE);
721 : 0 : }
722 : : else
723 : : {
724 : 2 : *out_child = g_file_get_child (g_file_enumerator_get_container (direnum), name);
725 : 2 : g_object_set_qdata_full ((GObject*)direnum, cached_child_quark, *out_child, (GDestroyNotify)g_object_unref);
726 : : }
727 : 0 : }
728 : 210 : if (out_info != NULL)
729 : : {
730 : 208 : g_object_set_qdata_full ((GObject*)direnum, cached_info_quark, ret_info, (GDestroyNotify)g_object_unref);
731 : 208 : *out_info = ret_info;
732 : 0 : }
733 : : else
734 : 2 : g_object_unref (ret_info);
735 : 0 : }
736 : : else
737 : : {
738 : 106 : if (out_info)
739 : 105 : *out_info = NULL;
740 : 106 : if (out_child)
741 : 1 : *out_child = NULL;
742 : : }
743 : :
744 : 316 : ret = TRUE;
745 : 316 : out:
746 : 316 : return ret;
747 : 0 : }
748 : :
749 : : /**
750 : : * g_file_enumerator_get_container:
751 : : * @enumerator: a file enumerator
752 : : *
753 : : * Get the [iface@Gio.File] container which is being enumerated.
754 : : *
755 : : * Returns: (transfer none): the file which is being enumerated
756 : : * Since: 2.18
757 : : */
758 : : GFile *
759 : 11 : g_file_enumerator_get_container (GFileEnumerator *enumerator)
760 : : {
761 : 11 : g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
762 : :
763 : 11 : return enumerator->priv->container;
764 : 0 : }
765 : :
766 : : /**
767 : : * g_file_enumerator_get_child:
768 : : * @enumerator: a file enumerator
769 : : * @info: a file info object received from [method@Gio.FileEnumerator.next_file]
770 : : * or the async equivalent
771 : : *
772 : : * Returns a new [iface@Gio.File] which refers to the file named by @info in the
773 : : * source directory of @enumerator.
774 : : *
775 : : * This function is primarily intended to be used inside loops with
776 : : * [method@Gio.FileEnumerator.next_file].
777 : : *
778 : : * To use this, [const@Gio.FILE_ATTRIBUTE_STANDARD_NAME] must have been listed
779 : : * in the attributes list used when creating the [class@Gio.FileEnumerator].
780 : : *
781 : : * This is a convenience method that's equivalent to:
782 : : * ```c
783 : : * char *name = g_file_info_get_name (info);
784 : : * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumerator), name);
785 : : * ```
786 : : *
787 : : * Returns: (transfer full): a file object for the file info object passed to it
788 : : * Since: 2.36
789 : : */
790 : : GFile *
791 : 55 : g_file_enumerator_get_child (GFileEnumerator *enumerator,
792 : : GFileInfo *info)
793 : : {
794 : : const gchar *name;
795 : :
796 : 55 : g_return_val_if_fail (G_IS_FILE_ENUMERATOR (enumerator), NULL);
797 : 55 : g_return_val_if_fail (G_IS_FILE_INFO (info), NULL);
798 : :
799 : 55 : name = g_file_info_get_name (info);
800 : :
801 : 55 : if (G_UNLIKELY (name == NULL))
802 : : {
803 : 0 : g_critical ("GFileEnumerator created without standard::name");
804 : : g_return_val_if_reached (NULL);
805 : 0 : }
806 : :
807 : 55 : return g_file_get_child (enumerator->priv->container, name);
808 : 0 : }
809 : :
810 : : static void
811 : 0 : next_async_op_free (GList *files)
812 : : {
813 : 0 : g_list_free_full (files, g_object_unref);
814 : 0 : }
815 : :
816 : : static void
817 : 24 : next_files_thread (GTask *task,
818 : : gpointer source_object,
819 : : gpointer task_data,
820 : : GCancellable *cancellable)
821 : : {
822 : 24 : GFileEnumerator *enumerator = source_object;
823 : 24 : int num_files = GPOINTER_TO_INT (task_data);
824 : : GFileEnumeratorClass *class;
825 : 24 : GList *files = NULL;
826 : 24 : GError *error = NULL;
827 : : GFileInfo *info;
828 : : int i;
829 : :
830 : 24 : class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
831 : :
832 : 72 : for (i = 0; i < num_files; i++)
833 : : {
834 : 72 : if (g_cancellable_set_error_if_cancelled (cancellable, &error))
835 : 0 : info = NULL;
836 : : else
837 : 72 : info = class->next_file (enumerator, cancellable, &error);
838 : :
839 : 72 : if (info == NULL)
840 : : {
841 : : /* If we get an error after first file, return that on next operation */
842 : 24 : if (error != NULL && i > 0)
843 : : {
844 : 0 : if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
845 : 0 : g_error_free (error); /* Never propagate cancel errors to other call */
846 : : else
847 : 0 : enumerator->priv->outstanding_error = error;
848 : 0 : error = NULL;
849 : 0 : }
850 : :
851 : 24 : break;
852 : : }
853 : : else
854 : 48 : files = g_list_prepend (files, info);
855 : 24 : }
856 : :
857 : 24 : if (error)
858 : : {
859 : 0 : g_list_free_full (files, g_object_unref);
860 : 0 : g_task_return_error (task, error);
861 : 0 : }
862 : : else
863 : 24 : g_task_return_pointer (task, files, (GDestroyNotify)next_async_op_free);
864 : 24 : }
865 : :
866 : : static void
867 : 24 : g_file_enumerator_real_next_files_async (GFileEnumerator *enumerator,
868 : : int num_files,
869 : : int io_priority,
870 : : GCancellable *cancellable,
871 : : GAsyncReadyCallback callback,
872 : : gpointer user_data)
873 : : {
874 : : GTask *task;
875 : :
876 : 24 : task = g_task_new (enumerator, cancellable, callback, user_data);
877 : 24 : g_task_set_source_tag (task, g_file_enumerator_real_next_files_async);
878 : 24 : g_task_set_task_data (task, GINT_TO_POINTER (num_files), NULL);
879 : 24 : g_task_set_priority (task, io_priority);
880 : :
881 : 24 : g_task_run_in_thread (task, next_files_thread);
882 : 24 : g_object_unref (task);
883 : 24 : }
884 : :
885 : : static GList *
886 : 24 : g_file_enumerator_real_next_files_finish (GFileEnumerator *enumerator,
887 : : GAsyncResult *result,
888 : : GError **error)
889 : : {
890 : 24 : g_return_val_if_fail (g_task_is_valid (result, enumerator), NULL);
891 : :
892 : 24 : return g_task_propagate_pointer (G_TASK (result), error);
893 : 12 : }
894 : :
895 : : static void
896 : 12 : close_async_thread (GTask *task,
897 : : gpointer source_object,
898 : : gpointer task_data,
899 : : GCancellable *cancellable)
900 : : {
901 : 12 : GFileEnumerator *enumerator = source_object;
902 : : GFileEnumeratorClass *class;
903 : 12 : GError *error = NULL;
904 : : gboolean result;
905 : :
906 : 12 : class = G_FILE_ENUMERATOR_GET_CLASS (enumerator);
907 : 12 : result = class->close_fn (enumerator, cancellable, &error);
908 : 12 : if (result)
909 : 12 : g_task_return_boolean (task, TRUE);
910 : : else
911 : 0 : g_task_return_error (task, error);
912 : 12 : }
913 : :
914 : : static void
915 : 12 : g_file_enumerator_real_close_async (GFileEnumerator *enumerator,
916 : : int io_priority,
917 : : GCancellable *cancellable,
918 : : GAsyncReadyCallback callback,
919 : : gpointer user_data)
920 : : {
921 : : GTask *task;
922 : :
923 : 12 : task = g_task_new (enumerator, cancellable, callback, user_data);
924 : 12 : g_task_set_source_tag (task, g_file_enumerator_real_close_async);
925 : 12 : g_task_set_priority (task, io_priority);
926 : :
927 : 12 : g_task_run_in_thread (task, close_async_thread);
928 : 12 : g_object_unref (task);
929 : 12 : }
930 : :
931 : : static gboolean
932 : 0 : g_file_enumerator_real_close_finish (GFileEnumerator *enumerator,
933 : : GAsyncResult *result,
934 : : GError **error)
935 : : {
936 : 0 : g_return_val_if_fail (g_task_is_valid (result, enumerator), FALSE);
937 : :
938 : 0 : return g_task_propagate_boolean (G_TASK (result), error);
939 : 0 : }
|
