source: appstream-generator/build/girepo/gio/Resource.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

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