1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD 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
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gio.FileEnumerator;
26 
27 private import gio.AsyncResultIF;
28 private import gio.Cancellable;
29 private import gio.FileIF;
30 private import gio.FileInfo;
31 private import gio.c.functions;
32 public  import gio.c.types;
33 private import glib.ErrorG;
34 private import glib.GException;
35 private import glib.ListG;
36 private import gobject.ObjectG;
37 public  import gtkc.giotypes;
38 
39 
40 /**
41  * #GFileEnumerator allows you to operate on a set of #GFiles,
42  * returning a #GFileInfo structure for each file enumerated (e.g.
43  * g_file_enumerate_children() will return a #GFileEnumerator for each
44  * of the children within a directory).
45  * 
46  * To get the next file's information from a #GFileEnumerator, use
47  * g_file_enumerator_next_file() or its asynchronous version,
48  * g_file_enumerator_next_files_async(). Note that the asynchronous
49  * version will return a list of #GFileInfos, whereas the
50  * synchronous will only return the next file in the enumerator.
51  * 
52  * The ordering of returned files is unspecified for non-Unix
53  * platforms; for more information, see g_dir_read_name().  On Unix,
54  * when operating on local files, returned files will be sorted by
55  * inode number.  Effectively you can assume that the ordering of
56  * returned files will be stable between successive calls (and
57  * applications) assuming the directory is unchanged.
58  * 
59  * If your application needs a specific ordering, such as by name or
60  * modification time, you will have to implement that in your
61  * application code.
62  * 
63  * To close a #GFileEnumerator, use g_file_enumerator_close(), or
64  * its asynchronous version, g_file_enumerator_close_async(). Once
65  * a #GFileEnumerator is closed, no further actions may be performed
66  * on it, and it should be freed with g_object_unref().
67  */
68 public class FileEnumerator : ObjectG
69 {
70 	/** the main Gtk struct */
71 	protected GFileEnumerator* gFileEnumerator;
72 
73 	/** Get the main Gtk struct */
74 	public GFileEnumerator* getFileEnumeratorStruct(bool transferOwnership = false)
75 	{
76 		if (transferOwnership)
77 			ownedRef = false;
78 		return gFileEnumerator;
79 	}
80 
81 	/** the main Gtk struct as a void* */
82 	protected override void* getStruct()
83 	{
84 		return cast(void*)gFileEnumerator;
85 	}
86 
87 	/**
88 	 * Sets our main struct and passes it to the parent class.
89 	 */
90 	public this (GFileEnumerator* gFileEnumerator, bool ownedRef = false)
91 	{
92 		this.gFileEnumerator = gFileEnumerator;
93 		super(cast(GObject*)gFileEnumerator, ownedRef);
94 	}
95 
96 
97 	/** */
98 	public static GType getType()
99 	{
100 		return g_file_enumerator_get_type();
101 	}
102 
103 	/**
104 	 * Releases all resources used by this enumerator, making the
105 	 * enumerator return %G_IO_ERROR_CLOSED on all calls.
106 	 *
107 	 * This will be automatically called when the last reference
108 	 * is dropped, but you might want to call this function to make
109 	 * sure resources are released as early as possible.
110 	 *
111 	 * Params:
112 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
113 	 *
114 	 * Returns: #TRUE on success or #FALSE on error.
115 	 *
116 	 * Throws: GException on failure.
117 	 */
118 	public bool close(Cancellable cancellable)
119 	{
120 		GError* err = null;
121 
122 		auto p = g_file_enumerator_close(gFileEnumerator, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0;
123 
124 		if (err !is null)
125 		{
126 			throw new GException( new ErrorG(err) );
127 		}
128 
129 		return p;
130 	}
131 
132 	/**
133 	 * Asynchronously closes the file enumerator.
134 	 *
135 	 * If @cancellable is not %NULL, then the operation can be cancelled by
136 	 * triggering the cancellable object from another thread. If the operation
137 	 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
138 	 * g_file_enumerator_close_finish().
139 	 *
140 	 * Params:
141 	 *     ioPriority = the [I/O priority][io-priority] of the request
142 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
143 	 *     callback = a #GAsyncReadyCallback to call when the request is satisfied
144 	 *     userData = the data to pass to callback function
145 	 */
146 	public void closeAsync(int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
147 	{
148 		g_file_enumerator_close_async(gFileEnumerator, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
149 	}
150 
151 	/**
152 	 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
153 	 *
154 	 * If the file enumerator was already closed when g_file_enumerator_close_async()
155 	 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
156 	 * return %FALSE. If the file enumerator had pending operation when the close
157 	 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
158 	 * return %FALSE.  If @cancellable was not %NULL, then the operation may have been
159 	 * cancelled by triggering the cancellable object from another thread. If the operation
160 	 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
161 	 * returned.
162 	 *
163 	 * Params:
164 	 *     result = a #GAsyncResult.
165 	 *
166 	 * Returns: %TRUE if the close operation has finished successfully.
167 	 *
168 	 * Throws: GException on failure.
169 	 */
170 	public bool closeFinish(AsyncResultIF result)
171 	{
172 		GError* err = null;
173 
174 		auto p = g_file_enumerator_close_finish(gFileEnumerator, (result is null) ? null : result.getAsyncResultStruct(), &err) != 0;
175 
176 		if (err !is null)
177 		{
178 			throw new GException( new ErrorG(err) );
179 		}
180 
181 		return p;
182 	}
183 
184 	/**
185 	 * Return a new #GFile which refers to the file named by @info in the source
186 	 * directory of @enumerator.  This function is primarily intended to be used
187 	 * inside loops with g_file_enumerator_next_file().
188 	 *
189 	 * This is a convenience method that's equivalent to:
190 	 * |[<!-- language="C" -->
191 	 * gchar *name = g_file_info_get_name (info);
192 	 * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
193 	 * name);
194 	 * ]|
195 	 *
196 	 * Params:
197 	 *     info = a #GFileInfo gotten from g_file_enumerator_next_file()
198 	 *         or the async equivalents.
199 	 *
200 	 * Returns: a #GFile for the #GFileInfo passed it.
201 	 *
202 	 * Since: 2.36
203 	 */
204 	public FileIF getChild(FileInfo info)
205 	{
206 		auto p = g_file_enumerator_get_child(gFileEnumerator, (info is null) ? null : info.getFileInfoStruct());
207 
208 		if(p is null)
209 		{
210 			return null;
211 		}
212 
213 		return ObjectG.getDObject!(FileIF)(cast(GFile*) p, true);
214 	}
215 
216 	/**
217 	 * Get the #GFile container which is being enumerated.
218 	 *
219 	 * Returns: the #GFile which is being enumerated.
220 	 *
221 	 * Since: 2.18
222 	 */
223 	public FileIF getContainer()
224 	{
225 		auto p = g_file_enumerator_get_container(gFileEnumerator);
226 
227 		if(p is null)
228 		{
229 			return null;
230 		}
231 
232 		return ObjectG.getDObject!(FileIF)(cast(GFile*) p);
233 	}
234 
235 	/**
236 	 * Checks if the file enumerator has pending operations.
237 	 *
238 	 * Returns: %TRUE if the @enumerator has pending operations.
239 	 */
240 	public bool hasPending()
241 	{
242 		return g_file_enumerator_has_pending(gFileEnumerator) != 0;
243 	}
244 
245 	/**
246 	 * Checks if the file enumerator has been closed.
247 	 *
248 	 * Returns: %TRUE if the @enumerator is closed.
249 	 */
250 	public bool isClosed()
251 	{
252 		return g_file_enumerator_is_closed(gFileEnumerator) != 0;
253 	}
254 
255 	/**
256 	 * This is a version of g_file_enumerator_next_file() that's easier to
257 	 * use correctly from C programs.  With g_file_enumerator_next_file(),
258 	 * the gboolean return value signifies "end of iteration or error", which
259 	 * requires allocation of a temporary #GError.
260 	 *
261 	 * In contrast, with this function, a %FALSE return from
262 	 * g_file_enumerator_iterate() *always* means
263 	 * "error".  End of iteration is signaled by @out_info or @out_child being %NULL.
264 	 *
265 	 * Another crucial difference is that the references for @out_info and
266 	 * @out_child are owned by @direnum (they are cached as hidden
267 	 * properties).  You must not unref them in your own code.  This makes
268 	 * memory management significantly easier for C code in combination
269 	 * with loops.
270 	 *
271 	 * Finally, this function optionally allows retrieving a #GFile as
272 	 * well.
273 	 *
274 	 * You must specify at least one of @out_info or @out_child.
275 	 *
276 	 * The code pattern for correctly using g_file_enumerator_iterate() from C
277 	 * is:
278 	 *
279 	 * |[
280 	 * direnum = g_file_enumerate_children (file, ...);
281 	 * while (TRUE)
282 	 * {
283 	 * GFileInfo *info;
284 	 * if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
285 	 * goto out;
286 	 * if (!info)
287 	 * break;
288 	 * ... do stuff with "info"; do not unref it! ...
289 	 * }
290 	 *
291 	 * out:
292 	 * g_object_unref (direnum); // Note: frees the last @info
293 	 * ]|
294 	 *
295 	 * Params:
296 	 *     outInfo = Output location for the next #GFileInfo, or %NULL
297 	 *     outChild = Output location for the next #GFile, or %NULL
298 	 *     cancellable = a #GCancellable
299 	 *
300 	 * Since: 2.44
301 	 *
302 	 * Throws: GException on failure.
303 	 */
304 	public bool iterate(out FileInfo outInfo, out FileIF outChild, Cancellable cancellable)
305 	{
306 		GFileInfo* outoutInfo = null;
307 		GFile* outoutChild = null;
308 		GError* err = null;
309 
310 		auto p = g_file_enumerator_iterate(gFileEnumerator, &outoutInfo, &outoutChild, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0;
311 
312 		if (err !is null)
313 		{
314 			throw new GException( new ErrorG(err) );
315 		}
316 
317 		outInfo = ObjectG.getDObject!(FileInfo)(outoutInfo);
318 		outChild = ObjectG.getDObject!(FileIF)(outoutChild);
319 
320 		return p;
321 	}
322 
323 	/**
324 	 * Returns information for the next file in the enumerated object.
325 	 * Will block until the information is available. The #GFileInfo
326 	 * returned from this function will contain attributes that match the
327 	 * attribute string that was passed when the #GFileEnumerator was created.
328 	 *
329 	 * See the documentation of #GFileEnumerator for information about the
330 	 * order of returned files.
331 	 *
332 	 * On error, returns %NULL and sets @error to the error. If the
333 	 * enumerator is at the end, %NULL will be returned and @error will
334 	 * be unset.
335 	 *
336 	 * Params:
337 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
338 	 *
339 	 * Returns: A #GFileInfo or %NULL on error
340 	 *     or end of enumerator.  Free the returned object with
341 	 *     g_object_unref() when no longer needed.
342 	 *
343 	 * Throws: GException on failure.
344 	 */
345 	public FileInfo nextFile(Cancellable cancellable)
346 	{
347 		GError* err = null;
348 
349 		auto p = g_file_enumerator_next_file(gFileEnumerator, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
350 
351 		if (err !is null)
352 		{
353 			throw new GException( new ErrorG(err) );
354 		}
355 
356 		if(p is null)
357 		{
358 			return null;
359 		}
360 
361 		return ObjectG.getDObject!(FileInfo)(cast(GFileInfo*) p, true);
362 	}
363 
364 	/**
365 	 * Request information for a number of files from the enumerator asynchronously.
366 	 * When all i/o for the operation is finished the @callback will be called with
367 	 * the requested information.
368 	 *
369 	 * See the documentation of #GFileEnumerator for information about the
370 	 * order of returned files.
371 	 *
372 	 * The callback can be called with less than @num_files files in case of error
373 	 * or at the end of the enumerator. In case of a partial error the callback will
374 	 * be called with any succeeding items and no error, and on the next request the
375 	 * error will be reported. If a request is cancelled the callback will be called
376 	 * with %G_IO_ERROR_CANCELLED.
377 	 *
378 	 * During an async request no other sync and async calls are allowed, and will
379 	 * result in %G_IO_ERROR_PENDING errors.
380 	 *
381 	 * Any outstanding i/o request with higher priority (lower numerical value) will
382 	 * be executed before an outstanding request with lower priority. Default
383 	 * priority is %G_PRIORITY_DEFAULT.
384 	 *
385 	 * Params:
386 	 *     numFiles = the number of file info objects to request
387 	 *     ioPriority = the [I/O priority][io-priority] of the request
388 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
389 	 *     callback = a #GAsyncReadyCallback to call when the request is satisfied
390 	 *     userData = the data to pass to callback function
391 	 */
392 	public void nextFilesAsync(int numFiles, int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
393 	{
394 		g_file_enumerator_next_files_async(gFileEnumerator, numFiles, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
395 	}
396 
397 	/**
398 	 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
399 	 *
400 	 * Params:
401 	 *     result = a #GAsyncResult.
402 	 *
403 	 * Returns: a #GList of #GFileInfos. You must free the list with
404 	 *     g_list_free() and unref the infos with g_object_unref() when you're
405 	 *     done with them.
406 	 *
407 	 * Throws: GException on failure.
408 	 */
409 	public ListG nextFilesFinish(AsyncResultIF result)
410 	{
411 		GError* err = null;
412 
413 		auto p = g_file_enumerator_next_files_finish(gFileEnumerator, (result is null) ? null : result.getAsyncResultStruct(), &err);
414 
415 		if (err !is null)
416 		{
417 			throw new GException( new ErrorG(err) );
418 		}
419 
420 		if(p is null)
421 		{
422 			return null;
423 		}
424 
425 		return new ListG(cast(GList*) p, true);
426 	}
427 
428 	/**
429 	 * Sets the file enumerator as having pending operations.
430 	 *
431 	 * Params:
432 	 *     pending = a boolean value.
433 	 */
434 	public void setPending(bool pending)
435 	{
436 		g_file_enumerator_set_pending(gFileEnumerator, pending);
437 	}
438 }