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