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.File;
30 private import gio.FileIF;
31 private import gio.FileInfo;
32 private import glib.ErrorG;
33 private import glib.GException;
34 private import glib.ListG;
35 private import gobject.ObjectG;
36 private import gtkc.gio;
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 	protected override void setStruct(GObject* obj)
88 	{
89 		gFileEnumerator = cast(GFileEnumerator*)obj;
90 		super.setStruct(obj);
91 	}
92 
93 	/**
94 	 * Sets our main struct and passes it to the parent class.
95 	 */
96 	public this (GFileEnumerator* gFileEnumerator, bool ownedRef = false)
97 	{
98 		this.gFileEnumerator = gFileEnumerator;
99 		super(cast(GObject*)gFileEnumerator, ownedRef);
100 	}
101 
102 
103 	/** */
104 	public static GType getType()
105 	{
106 		return g_file_enumerator_get_type();
107 	}
108 
109 	/**
110 	 * Releases all resources used by this enumerator, making the
111 	 * enumerator return %G_IO_ERROR_CLOSED on all calls.
112 	 *
113 	 * This will be automatically called when the last reference
114 	 * is dropped, but you might want to call this function to make
115 	 * sure resources are released as early as possible.
116 	 *
117 	 * Params:
118 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
119 	 *
120 	 * Returns: #TRUE on success or #FALSE on error.
121 	 *
122 	 * Throws: GException on failure.
123 	 */
124 	public bool close(Cancellable cancellable)
125 	{
126 		GError* err = null;
127 		
128 		auto p = g_file_enumerator_close(gFileEnumerator, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0;
129 		
130 		if (err !is null)
131 		{
132 			throw new GException( new ErrorG(err) );
133 		}
134 		
135 		return p;
136 	}
137 
138 	/**
139 	 * Asynchronously closes the file enumerator.
140 	 *
141 	 * If @cancellable is not %NULL, then the operation can be cancelled by
142 	 * triggering the cancellable object from another thread. If the operation
143 	 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
144 	 * g_file_enumerator_close_finish().
145 	 *
146 	 * Params:
147 	 *     ioPriority = the [I/O priority][io-priority] of the request
148 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
149 	 *     callback = a #GAsyncReadyCallback to call when the request is satisfied
150 	 *     userData = the data to pass to callback function
151 	 */
152 	public void closeAsync(int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
153 	{
154 		g_file_enumerator_close_async(gFileEnumerator, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
155 	}
156 
157 	/**
158 	 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
159 	 *
160 	 * If the file enumerator was already closed when g_file_enumerator_close_async()
161 	 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
162 	 * return %FALSE. If the file enumerator had pending operation when the close
163 	 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
164 	 * return %FALSE.  If @cancellable was not %NULL, then the operation may have been
165 	 * cancelled by triggering the cancellable object from another thread. If the operation
166 	 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
167 	 * returned.
168 	 *
169 	 * Params:
170 	 *     result = a #GAsyncResult.
171 	 *
172 	 * Returns: %TRUE if the close operation has finished successfully.
173 	 *
174 	 * Throws: GException on failure.
175 	 */
176 	public bool closeFinish(AsyncResultIF result)
177 	{
178 		GError* err = null;
179 		
180 		auto p = g_file_enumerator_close_finish(gFileEnumerator, (result is null) ? null : result.getAsyncResultStruct(), &err) != 0;
181 		
182 		if (err !is null)
183 		{
184 			throw new GException( new ErrorG(err) );
185 		}
186 		
187 		return p;
188 	}
189 
190 	/**
191 	 * Return a new #GFile which refers to the file named by @info in the source
192 	 * directory of @enumerator.  This function is primarily intended to be used
193 	 * inside loops with g_file_enumerator_next_file().
194 	 *
195 	 * This is a convenience method that's equivalent to:
196 	 * |[<!-- language="C" -->
197 	 * gchar *name = g_file_info_get_name (info);
198 	 * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
199 	 * name);
200 	 * ]|
201 	 *
202 	 * Params:
203 	 *     info = a #GFileInfo gotten from g_file_enumerator_next_file()
204 	 *         or the async equivalents.
205 	 *
206 	 * Returns: a #GFile for the #GFileInfo passed it.
207 	 *
208 	 * Since: 2.36
209 	 */
210 	public FileIF getChild(FileInfo info)
211 	{
212 		auto p = g_file_enumerator_get_child(gFileEnumerator, (info is null) ? null : info.getFileInfoStruct());
213 		
214 		if(p is null)
215 		{
216 			return null;
217 		}
218 		
219 		return ObjectG.getDObject!(File, FileIF)(cast(GFile*) p, true);
220 	}
221 
222 	/**
223 	 * Get the #GFile container which is being enumerated.
224 	 *
225 	 * Returns: the #GFile which is being enumerated.
226 	 *
227 	 * Since: 2.18
228 	 */
229 	public FileIF getContainer()
230 	{
231 		auto p = g_file_enumerator_get_container(gFileEnumerator);
232 		
233 		if(p is null)
234 		{
235 			return null;
236 		}
237 		
238 		return ObjectG.getDObject!(File, FileIF)(cast(GFile*) p);
239 	}
240 
241 	/**
242 	 * Checks if the file enumerator has pending operations.
243 	 *
244 	 * Returns: %TRUE if the @enumerator has pending operations.
245 	 */
246 	public bool hasPending()
247 	{
248 		return g_file_enumerator_has_pending(gFileEnumerator) != 0;
249 	}
250 
251 	/**
252 	 * Checks if the file enumerator has been closed.
253 	 *
254 	 * Returns: %TRUE if the @enumerator is closed.
255 	 */
256 	public bool isClosed()
257 	{
258 		return g_file_enumerator_is_closed(gFileEnumerator) != 0;
259 	}
260 
261 	/**
262 	 * This is a version of g_file_enumerator_next_file() that's easier to
263 	 * use correctly from C programs.  With g_file_enumerator_next_file(),
264 	 * the gboolean return value signifies "end of iteration or error", which
265 	 * requires allocation of a temporary #GError.
266 	 *
267 	 * In contrast, with this function, a %FALSE return from
268 	 * g_file_enumerator_iterate() *always* means
269 	 * "error".  End of iteration is signaled by @out_info or @out_child being %NULL.
270 	 *
271 	 * Another crucial difference is that the references for @out_info and
272 	 * @out_child are owned by @direnum (they are cached as hidden
273 	 * properties).  You must not unref them in your own code.  This makes
274 	 * memory management significantly easier for C code in combination
275 	 * with loops.
276 	 *
277 	 * Finally, this function optionally allows retrieving a #GFile as
278 	 * well.
279 	 *
280 	 * You must specify at least one of @out_info or @out_child.
281 	 *
282 	 * The code pattern for correctly using g_file_enumerator_iterate() from C
283 	 * is:
284 	 *
285 	 * |[
286 	 * direnum = g_file_enumerate_children (file, ...);
287 	 * while (TRUE)
288 	 * {
289 	 * GFileInfo *info;
290 	 * if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
291 	 * goto out;
292 	 * if (!info)
293 	 * break;
294 	 * ... do stuff with "info"; do not unref it! ...
295 	 * }
296 	 *
297 	 * out:
298 	 * g_object_unref (direnum); // Note: frees the last @info
299 	 * ]|
300 	 *
301 	 * Params:
302 	 *     outInfo = Output location for the next #GFileInfo, or %NULL
303 	 *     outChild = Output location for the next #GFile, or %NULL
304 	 *     cancellable = a #GCancellable
305 	 *
306 	 * Since: 2.44
307 	 *
308 	 * Throws: GException on failure.
309 	 */
310 	public bool iterate(out FileInfo outInfo, out FileIF outChild, Cancellable cancellable)
311 	{
312 		GFileInfo* outoutInfo = null;
313 		GFile* outoutChild = null;
314 		GError* err = null;
315 		
316 		auto p = g_file_enumerator_iterate(gFileEnumerator, &outoutInfo, &outoutChild, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0;
317 		
318 		if (err !is null)
319 		{
320 			throw new GException( new ErrorG(err) );
321 		}
322 		
323 		outInfo = ObjectG.getDObject!(FileInfo)(outoutInfo);
324 		outChild = ObjectG.getDObject!(File, FileIF)(outoutChild);
325 		
326 		return p;
327 	}
328 
329 	/**
330 	 * Returns information for the next file in the enumerated object.
331 	 * Will block until the information is available. The #GFileInfo
332 	 * returned from this function will contain attributes that match the
333 	 * attribute string that was passed when the #GFileEnumerator was created.
334 	 *
335 	 * See the documentation of #GFileEnumerator for information about the
336 	 * order of returned files.
337 	 *
338 	 * On error, returns %NULL and sets @error to the error. If the
339 	 * enumerator is at the end, %NULL will be returned and @error will
340 	 * be unset.
341 	 *
342 	 * Params:
343 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
344 	 *
345 	 * Returns: A #GFileInfo or %NULL on error
346 	 *     or end of enumerator.  Free the returned object with
347 	 *     g_object_unref() when no longer needed.
348 	 *
349 	 * Throws: GException on failure.
350 	 */
351 	public FileInfo nextFile(Cancellable cancellable)
352 	{
353 		GError* err = null;
354 		
355 		auto p = g_file_enumerator_next_file(gFileEnumerator, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
356 		
357 		if (err !is null)
358 		{
359 			throw new GException( new ErrorG(err) );
360 		}
361 		
362 		if(p is null)
363 		{
364 			return null;
365 		}
366 		
367 		return ObjectG.getDObject!(FileInfo)(cast(GFileInfo*) p, true);
368 	}
369 
370 	/**
371 	 * Request information for a number of files from the enumerator asynchronously.
372 	 * When all i/o for the operation is finished the @callback will be called with
373 	 * the requested information.
374 	 *
375 	 * See the documentation of #GFileEnumerator for information about the
376 	 * order of returned files.
377 	 *
378 	 * The callback can be called with less than @num_files files in case of error
379 	 * or at the end of the enumerator. In case of a partial error the callback will
380 	 * be called with any succeeding items and no error, and on the next request the
381 	 * error will be reported. If a request is cancelled the callback will be called
382 	 * with %G_IO_ERROR_CANCELLED.
383 	 *
384 	 * During an async request no other sync and async calls are allowed, and will
385 	 * result in %G_IO_ERROR_PENDING errors.
386 	 *
387 	 * Any outstanding i/o request with higher priority (lower numerical value) will
388 	 * be executed before an outstanding request with lower priority. Default
389 	 * priority is %G_PRIORITY_DEFAULT.
390 	 *
391 	 * Params:
392 	 *     numFiles = the number of file info objects to request
393 	 *     ioPriority = the [I/O priority][io-priority] of the request
394 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
395 	 *     callback = a #GAsyncReadyCallback to call when the request is satisfied
396 	 *     userData = the data to pass to callback function
397 	 */
398 	public void nextFilesAsync(int numFiles, int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
399 	{
400 		g_file_enumerator_next_files_async(gFileEnumerator, numFiles, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
401 	}
402 
403 	/**
404 	 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
405 	 *
406 	 * Params:
407 	 *     result = a #GAsyncResult.
408 	 *
409 	 * Returns: a #GList of #GFileInfos. You must free the list with
410 	 *     g_list_free() and unref the infos with g_object_unref() when you're
411 	 *     done with them.
412 	 *
413 	 * Throws: GException on failure.
414 	 */
415 	public ListG nextFilesFinish(AsyncResultIF result)
416 	{
417 		GError* err = null;
418 		
419 		auto p = g_file_enumerator_next_files_finish(gFileEnumerator, (result is null) ? null : result.getAsyncResultStruct(), &err);
420 		
421 		if (err !is null)
422 		{
423 			throw new GException( new ErrorG(err) );
424 		}
425 		
426 		if(p is null)
427 		{
428 			return null;
429 		}
430 		
431 		return new ListG(cast(GList*) p, true);
432 	}
433 
434 	/**
435 	 * Sets the file enumerator as having pending operations.
436 	 *
437 	 * Params:
438 	 *     pending = a boolean value.
439 	 */
440 	public void setPending(bool pending)
441 	{
442 		g_file_enumerator_set_pending(gFileEnumerator, pending);
443 	}
444 }