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.Resource;
26 
27 private import gio.InputStream;
28 private import gio.c.functions;
29 public  import gio.c.types;
30 private import glib.Bytes;
31 private import glib.ConstructionException;
32 private import glib.ErrorG;
33 private import glib.GException;
34 private import glib.Str;
35 private import gobject.ObjectG;
36 public  import gtkc.giotypes;
37 private import gtkd.Loader;
38 
39 
40 /**
41  * Applications and libraries often contain binary or textual data that is
42  * really part of the application, rather than user data. For instance
43  * #GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files,
44  * icons, etc. These are often shipped as files in `$datadir/appname`, or
45  * manually included as literal strings in the code.
46  * 
47  * The #GResource API and the [glib-compile-resources][glib-compile-resources] program
48  * provide a convenient and efficient alternative to this which has some nice properties. You
49  * maintain the files as normal files, so its easy to edit them, but during the build the files
50  * are combined into a binary bundle that is linked into the executable. This means that loading
51  * the resource files are efficient (as they are already in memory, shared with other instances) and
52  * simple (no need to check for things like I/O errors or locate the files in the filesystem). It
53  * also makes it easier to create relocatable applications.
54  * 
55  * Resource files can also be marked as compressed. Such files will be included in the resource bundle
56  * in a compressed form, but will be automatically uncompressed when the resource is used. This
57  * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
58  * 
59  * Resource files can also be marked to be preprocessed, by setting the value of the
60  * `preprocess` attribute to a comma-separated list of preprocessing options.
61  * The only options currently supported are:
62  * 
63  * `xml-stripblanks` which will use the xmllint command
64  * to strip ignorable whitespace from the XML file. For this to work,
65  * the `XMLLINT` environment variable must be set to the full path to
66  * the xmllint executable, or xmllint must be in the `PATH`; otherwise
67  * the preprocessing step is skipped.
68  * 
69  * `to-pixdata` which will use the gdk-pixbuf-pixdata command to convert
70  * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside
71  * the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata
72  * program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable must be
73  * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will
74  * abort.
75  * 
76  * Resource files will be exported in the GResource namespace using the
77  * combination of the given `prefix` and the filename from the `file` element.
78  * The `alias` attribute can be used to alter the filename to expose them at a
79  * different location in the resource namespace. Typically, this is used to
80  * include files from a different source directory without exposing the source
81  * directory in the resource namespace, as in the example below.
82  * 
83  * Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program
84  * which takes an XML file that describes the bundle, and a set of files that the XML references. These
85  * are combined into a binary resource bundle.
86  * 
87  * An example resource description:
88  * |[
89  * <?xml version="1.0" encoding="UTF-8"?>
90  * <gresources>
91  * <gresource prefix="/org/gtk/Example">
92  * <file>data/splashscreen.png</file>
93  * <file compressed="true">dialog.ui</file>
94  * <file preprocess="xml-stripblanks">menumarkup.xml</file>
95  * <file alias="example.css">data/example.css</file>
96  * </gresource>
97  * </gresources>
98  * ]|
99  * 
100  * This will create a resource bundle with the following files:
101  * |[
102  * /org/gtk/Example/data/splashscreen.png
103  * /org/gtk/Example/dialog.ui
104  * /org/gtk/Example/menumarkup.xml
105  * /org/gtk/Example/example.css
106  * ]|
107  * 
108  * Note that all resources in the process share the same namespace, so use Java-style
109  * path prefixes (like in the above example) to avoid conflicts.
110  * 
111  * You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a
112  * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
113  * --generate-header arguments to create a source file and header to link directly into your application.
114  * This will generate `get_resource()`, `register_resource()` and
115  * `unregister_resource()` functions, prefixed by the `--c-name` argument passed
116  * to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns
117  * the generated #GResource object. The register and unregister functions
118  * register the resource so its files can be accessed using
119  * g_resources_lookup_data().
120  * 
121  * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
122  * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
123  * to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
124  * the resource data.
125  * 
126  * Some higher-level APIs, such as #GtkApplication, will automatically load
127  * resources from certain well-known paths in the resource namespace as a
128  * convenience. See the documentation for those APIs for details.
129  * 
130  * There are two forms of the generated source, the default version uses the compiler support for constructor
131  * and destructor functions (where available) to automatically create and register the #GResource on startup
132  * or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created
133  * instead. This requires an explicit initialization call in your application/library, but it works on all platforms,
134  * even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.)
135  * 
136  * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
137  * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
138  * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
139  * are for your own resources, and resource data is often used once, during parsing, and then released.
140  * 
141  * When debugging a program or testing a change to an installed version, it is often useful to be able to
142  * replace resources in the program or library, without recompiling, for debugging or quick hacking and testing
143  * purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay
144  * resources with replacements from the filesystem.  It is a colon-separated list of substitutions to perform
145  * during resource lookups.
146  * 
147  * A substitution has the form
148  * 
149  * |[
150  * /org/gtk/libgtk=/home/desrt/gtk-overlay
151  * ]|
152  * 
153  * The part before the `=` is the resource subpath for which the overlay applies.  The part after is a
154  * filesystem path which contains files and subdirectories as you would like to be loaded as resources with the
155  * equivalent names.
156  * 
157  * In the example above, if an application tried to load a resource with the resource path
158  * `/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path
159  * `/home/desrt/gtk-overlay/ui/gtkdialog.ui`.  If a file was found there, it would be used instead.  This is an
160  * overlay, not an outright replacement, which means that if a file is not found at that path, the built-in
161  * version will be used instead.  Whiteouts are not currently supported.
162  * 
163  * Substitutions must start with a slash, and must not contain a trailing slash before the '='.  The path after
164  * the slash should ideally be absolute, but this is not strictly required.  It is possible to overlay the
165  * location of a single resource with an individual file.
166  *
167  * Since: 2.32
168  */
169 public class Resource
170 {
171 	/** the main Gtk struct */
172 	protected GResource* gResource;
173 	protected bool ownedRef;
174 
175 	/** Get the main Gtk struct */
176 	public GResource* getResourceStruct(bool transferOwnership = false)
177 	{
178 		if (transferOwnership)
179 			ownedRef = false;
180 		return gResource;
181 	}
182 
183 	/** the main Gtk struct as a void* */
184 	protected void* getStruct()
185 	{
186 		return cast(void*)gResource;
187 	}
188 
189 	/**
190 	 * Sets our main struct and passes it to the parent class.
191 	 */
192 	public this (GResource* gResource, bool ownedRef = false)
193 	{
194 		this.gResource = gResource;
195 		this.ownedRef = ownedRef;
196 	}
197 
198 	~this ()
199 	{
200 		if ( Linker.isLoaded(LIBRARY_GIO) && ownedRef )
201 			g_resource_unref(gResource);
202 	}
203 
204 
205 	/** */
206 	public static GType getType()
207 	{
208 		return g_resource_get_type();
209 	}
210 
211 	/**
212 	 * Creates a GResource from a reference to the binary resource bundle.
213 	 * This will keep a reference to @data while the resource lives, so
214 	 * the data should not be modified or freed.
215 	 *
216 	 * If you want to use this resource in the global resource namespace you need
217 	 * to register it with g_resources_register().
218 	 *
219 	 * Params:
220 	 *     data = A #GBytes
221 	 *
222 	 * Returns: a new #GResource, or %NULL on error
223 	 *
224 	 * Since: 2.32
225 	 *
226 	 * Throws: GException on failure.
227 	 * Throws: ConstructionException GTK+ fails to create the object.
228 	 */
229 	public this(Bytes data)
230 	{
231 		GError* err = null;
232 
233 		auto p = g_resource_new_from_data((data is null) ? null : data.getBytesStruct(), &err);
234 
235 		if (err !is null)
236 		{
237 			throw new GException( new ErrorG(err) );
238 		}
239 
240 		if(p is null)
241 		{
242 			throw new ConstructionException("null returned by new_from_data");
243 		}
244 
245 		this(cast(GResource*) p);
246 	}
247 
248 	/**
249 	 * Registers the resource with the process-global set of resources.
250 	 * Once a resource is registered the files in it can be accessed
251 	 * with the global resource lookup functions like g_resources_lookup_data().
252 	 *
253 	 * Params:
254 	 *     resource = A #GResource
255 	 *
256 	 * Since: 2.32
257 	 */
258 	public static void register(Resource resource)
259 	{
260 		g_resources_register((resource is null) ? null : resource.getResourceStruct());
261 	}
262 
263 	/**
264 	 * Unregisters the resource from the process-global set of resources.
265 	 *
266 	 * Params:
267 	 *     resource = A #GResource
268 	 *
269 	 * Since: 2.32
270 	 */
271 	public static void unregister(Resource resource)
272 	{
273 		g_resources_unregister((resource is null) ? null : resource.getResourceStruct());
274 	}
275 
276 	/**
277 	 * Returns all the names of children at the specified @path in the resource.
278 	 * The return result is a %NULL terminated list of strings which should
279 	 * be released with g_strfreev().
280 	 *
281 	 * If @path is invalid or does not exist in the #GResource,
282 	 * %G_RESOURCE_ERROR_NOT_FOUND will be returned.
283 	 *
284 	 * @lookup_flags controls the behaviour of the lookup.
285 	 *
286 	 * Params:
287 	 *     path = A pathname inside the resource
288 	 *     lookupFlags = A #GResourceLookupFlags
289 	 *
290 	 * Returns: an array of constant strings
291 	 *
292 	 * Since: 2.32
293 	 *
294 	 * Throws: GException on failure.
295 	 */
296 	public string[] enumerateChildren(string path, GResourceLookupFlags lookupFlags)
297 	{
298 		GError* err = null;
299 
300 		auto retStr = g_resource_enumerate_children(gResource, Str.toStringz(path), lookupFlags, &err);
301 
302 		if (err !is null)
303 		{
304 			throw new GException( new ErrorG(err) );
305 		}
306 
307 		scope(exit) Str.freeStringArray(retStr);
308 		return Str.toStringArray(retStr);
309 	}
310 
311 	/**
312 	 * Looks for a file at the specified @path in the resource and
313 	 * if found returns information about it.
314 	 *
315 	 * @lookup_flags controls the behaviour of the lookup.
316 	 *
317 	 * Params:
318 	 *     path = A pathname inside the resource
319 	 *     lookupFlags = A #GResourceLookupFlags
320 	 *     size = a location to place the length of the contents of the file,
321 	 *         or %NULL if the length is not needed
322 	 *     flags = a location to place the flags about the file,
323 	 *         or %NULL if the length is not needed
324 	 *
325 	 * Returns: %TRUE if the file was found. %FALSE if there were errors
326 	 *
327 	 * Since: 2.32
328 	 *
329 	 * Throws: GException on failure.
330 	 */
331 	public bool getInfo(string path, GResourceLookupFlags lookupFlags, out size_t size, out uint flags)
332 	{
333 		GError* err = null;
334 
335 		auto p = g_resource_get_info(gResource, Str.toStringz(path), lookupFlags, &size, &flags, &err) != 0;
336 
337 		if (err !is null)
338 		{
339 			throw new GException( new ErrorG(err) );
340 		}
341 
342 		return p;
343 	}
344 
345 	/**
346 	 * Looks for a file at the specified @path in the resource and
347 	 * returns a #GBytes that lets you directly access the data in
348 	 * memory.
349 	 *
350 	 * The data is always followed by a zero byte, so you
351 	 * can safely use the data as a C string. However, that byte
352 	 * is not included in the size of the GBytes.
353 	 *
354 	 * For uncompressed resource files this is a pointer directly into
355 	 * the resource bundle, which is typically in some readonly data section
356 	 * in the program binary. For compressed files we allocate memory on
357 	 * the heap and automatically uncompress the data.
358 	 *
359 	 * @lookup_flags controls the behaviour of the lookup.
360 	 *
361 	 * Params:
362 	 *     path = A pathname inside the resource
363 	 *     lookupFlags = A #GResourceLookupFlags
364 	 *
365 	 * Returns: #GBytes or %NULL on error.
366 	 *     Free the returned object with g_bytes_unref()
367 	 *
368 	 * Since: 2.32
369 	 *
370 	 * Throws: GException on failure.
371 	 */
372 	public Bytes lookupData(string path, GResourceLookupFlags lookupFlags)
373 	{
374 		GError* err = null;
375 
376 		auto p = g_resource_lookup_data(gResource, Str.toStringz(path), lookupFlags, &err);
377 
378 		if (err !is null)
379 		{
380 			throw new GException( new ErrorG(err) );
381 		}
382 
383 		if(p is null)
384 		{
385 			return null;
386 		}
387 
388 		return new Bytes(cast(GBytes*) p, true);
389 	}
390 
391 	/**
392 	 * Looks for a file at the specified @path in the resource and
393 	 * returns a #GInputStream that lets you read the data.
394 	 *
395 	 * @lookup_flags controls the behaviour of the lookup.
396 	 *
397 	 * Params:
398 	 *     path = A pathname inside the resource
399 	 *     lookupFlags = A #GResourceLookupFlags
400 	 *
401 	 * Returns: #GInputStream or %NULL on error.
402 	 *     Free the returned object with g_object_unref()
403 	 *
404 	 * Since: 2.32
405 	 *
406 	 * Throws: GException on failure.
407 	 */
408 	public InputStream openStream(string path, GResourceLookupFlags lookupFlags)
409 	{
410 		GError* err = null;
411 
412 		auto p = g_resource_open_stream(gResource, Str.toStringz(path), lookupFlags, &err);
413 
414 		if (err !is null)
415 		{
416 			throw new GException( new ErrorG(err) );
417 		}
418 
419 		if(p is null)
420 		{
421 			return null;
422 		}
423 
424 		return ObjectG.getDObject!(InputStream)(cast(GInputStream*) p, true);
425 	}
426 
427 	/**
428 	 * Atomically increments the reference count of @resource by one. This
429 	 * function is MT-safe and may be called from any thread.
430 	 *
431 	 * Returns: The passed in #GResource
432 	 *
433 	 * Since: 2.32
434 	 */
435 	public Resource doref()
436 	{
437 		auto p = g_resource_ref(gResource);
438 
439 		if(p is null)
440 		{
441 			return null;
442 		}
443 
444 		return ObjectG.getDObject!(Resource)(cast(GResource*) p, true);
445 	}
446 
447 	/**
448 	 * Atomically decrements the reference count of @resource by one. If the
449 	 * reference count drops to 0, all memory allocated by the resource is
450 	 * released. This function is MT-safe and may be called from any
451 	 * thread.
452 	 *
453 	 * Since: 2.32
454 	 */
455 	public void unref()
456 	{
457 		g_resource_unref(gResource);
458 	}
459 
460 	/**
461 	 * Loads a binary resource bundle and creates a #GResource representation of it, allowing
462 	 * you to query it for data.
463 	 *
464 	 * If you want to use this resource in the global resource namespace you need
465 	 * to register it with g_resources_register().
466 	 *
467 	 * Params:
468 	 *     filename = the path of a filename to load, in the GLib filename encoding
469 	 *
470 	 * Returns: a new #GResource, or %NULL on error
471 	 *
472 	 * Since: 2.32
473 	 *
474 	 * Throws: GException on failure.
475 	 */
476 	public static Resource load(string filename)
477 	{
478 		GError* err = null;
479 
480 		auto p = g_resource_load(Str.toStringz(filename), &err);
481 
482 		if (err !is null)
483 		{
484 			throw new GException( new ErrorG(err) );
485 		}
486 
487 		if(p is null)
488 		{
489 			return null;
490 		}
491 
492 		return ObjectG.getDObject!(Resource)(cast(GResource*) p, true);
493 	}
494 
495 	/**
496 	 * Returns all the names of children at the specified @path in the set of
497 	 * globally registered resources.
498 	 * The return result is a %NULL terminated list of strings which should
499 	 * be released with g_strfreev().
500 	 *
501 	 * @lookup_flags controls the behaviour of the lookup.
502 	 *
503 	 * Params:
504 	 *     path = A pathname inside the resource
505 	 *     lookupFlags = A #GResourceLookupFlags
506 	 *
507 	 * Returns: an array of constant strings
508 	 *
509 	 * Since: 2.32
510 	 *
511 	 * Throws: GException on failure.
512 	 */
513 	public static string[] resourcesEnumerateChildren(string path, GResourceLookupFlags lookupFlags)
514 	{
515 		GError* err = null;
516 
517 		auto retStr = g_resources_enumerate_children(Str.toStringz(path), lookupFlags, &err);
518 
519 		if (err !is null)
520 		{
521 			throw new GException( new ErrorG(err) );
522 		}
523 
524 		scope(exit) Str.freeStringArray(retStr);
525 		return Str.toStringArray(retStr);
526 	}
527 
528 	/**
529 	 * Looks for a file at the specified @path in the set of
530 	 * globally registered resources and if found returns information about it.
531 	 *
532 	 * @lookup_flags controls the behaviour of the lookup.
533 	 *
534 	 * Params:
535 	 *     path = A pathname inside the resource
536 	 *     lookupFlags = A #GResourceLookupFlags
537 	 *     size = a location to place the length of the contents of the file,
538 	 *         or %NULL if the length is not needed
539 	 *     flags = a location to place the #GResourceFlags about the file,
540 	 *         or %NULL if the flags are not needed
541 	 *
542 	 * Returns: %TRUE if the file was found. %FALSE if there were errors
543 	 *
544 	 * Since: 2.32
545 	 *
546 	 * Throws: GException on failure.
547 	 */
548 	public static bool resourcesGetInfo(string path, GResourceLookupFlags lookupFlags, out size_t size, out uint flags)
549 	{
550 		GError* err = null;
551 
552 		auto p = g_resources_get_info(Str.toStringz(path), lookupFlags, &size, &flags, &err) != 0;
553 
554 		if (err !is null)
555 		{
556 			throw new GException( new ErrorG(err) );
557 		}
558 
559 		return p;
560 	}
561 
562 	/**
563 	 * Looks for a file at the specified @path in the set of
564 	 * globally registered resources and returns a #GBytes that
565 	 * lets you directly access the data in memory.
566 	 *
567 	 * The data is always followed by a zero byte, so you
568 	 * can safely use the data as a C string. However, that byte
569 	 * is not included in the size of the GBytes.
570 	 *
571 	 * For uncompressed resource files this is a pointer directly into
572 	 * the resource bundle, which is typically in some readonly data section
573 	 * in the program binary. For compressed files we allocate memory on
574 	 * the heap and automatically uncompress the data.
575 	 *
576 	 * @lookup_flags controls the behaviour of the lookup.
577 	 *
578 	 * Params:
579 	 *     path = A pathname inside the resource
580 	 *     lookupFlags = A #GResourceLookupFlags
581 	 *
582 	 * Returns: #GBytes or %NULL on error.
583 	 *     Free the returned object with g_bytes_unref()
584 	 *
585 	 * Since: 2.32
586 	 *
587 	 * Throws: GException on failure.
588 	 */
589 	public static Bytes resourcesLookupData(string path, GResourceLookupFlags lookupFlags)
590 	{
591 		GError* err = null;
592 
593 		auto p = g_resources_lookup_data(Str.toStringz(path), lookupFlags, &err);
594 
595 		if (err !is null)
596 		{
597 			throw new GException( new ErrorG(err) );
598 		}
599 
600 		if(p is null)
601 		{
602 			return null;
603 		}
604 
605 		return new Bytes(cast(GBytes*) p, true);
606 	}
607 
608 	/**
609 	 * Looks for a file at the specified @path in the set of
610 	 * globally registered resources and returns a #GInputStream
611 	 * that lets you read the data.
612 	 *
613 	 * @lookup_flags controls the behaviour of the lookup.
614 	 *
615 	 * Params:
616 	 *     path = A pathname inside the resource
617 	 *     lookupFlags = A #GResourceLookupFlags
618 	 *
619 	 * Returns: #GInputStream or %NULL on error.
620 	 *     Free the returned object with g_object_unref()
621 	 *
622 	 * Since: 2.32
623 	 *
624 	 * Throws: GException on failure.
625 	 */
626 	public static InputStream resourcesOpenStream(string path, GResourceLookupFlags lookupFlags)
627 	{
628 		GError* err = null;
629 
630 		auto p = g_resources_open_stream(Str.toStringz(path), lookupFlags, &err);
631 
632 		if (err !is null)
633 		{
634 			throw new GException( new ErrorG(err) );
635 		}
636 
637 		if(p is null)
638 		{
639 			return null;
640 		}
641 
642 		return ObjectG.getDObject!(InputStream)(cast(GInputStream*) p, true);
643 	}
644 }