gio/auto/

resource.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{ffi, InputStream, ResourceLookupFlags};
use glib::translate::*;

glib::wrapper! {
    /// Applications and libraries often contain binary or textual data that is
    /// really part of the application, rather than user data. For instance
    /// [`GtkBuilder`](https://docs.gtk.org/gtk4/class.Builder.html) `.ui` files,
    /// splashscreen images, [`Menu`][crate::Menu] markup XML, CSS files, icons, etc.
    /// These are often shipped as files in `$datadir/appname`, or manually
    /// included as literal strings in the code.
    ///
    /// The `GResource` API and the
    /// [`glib-compile-resources`](glib-compile-resources.html) program provide a
    /// convenient and efficient alternative to this which has some nice properties.
    /// You maintain the files as normal files, so it’s easy to edit them, but during
    /// the build the files are combined into a binary bundle that is linked into the
    /// executable. This means that loading the resource files are efficient (as they
    /// are already in memory, shared with other instances) and simple (no need to
    /// check for things like I/O errors or locate the files in the filesystem). It
    /// also makes it easier to create relocatable applications.
    ///
    /// Resource files can also be marked as compressed. Such files will be included
    /// in the resource bundle in a compressed form, but will be automatically
    /// uncompressed when the resource is used. This is very useful e.g. for larger
    /// text files that are parsed once (or rarely) and then thrown away.
    ///
    /// Resource files can also be marked to be preprocessed, by setting the value of the
    /// `preprocess` attribute to a comma-separated list of preprocessing options.
    /// The only options currently supported are:
    ///
    ///  - `xml-stripblanks` which will use the [`xmllint`](man:xmllint(1)) command
    ///    to strip ignorable whitespace from the XML file. For this to work,
    ///    the `XMLLINT` environment variable must be set to the full path to
    ///    the xmllint executable, or xmllint must be in the `PATH`; otherwise
    ///    the preprocessing step is skipped.
    ///
    ///  - `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the
    ///    `gdk-pixbuf-pixdata` command to convert images to the [`GdkPixdata`](https://docs.gtk.org/gdk-pixbuf/class.Pixdata.html)
    ///    format, which allows you to create pixbufs directly using the data inside
    ///    the resource file, rather than an (uncompressed) copy of it. For this, the
    ///    `gdk-pixbuf-pixdata` program must be in the `PATH`, or the
    ///    `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to
    ///    the `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will
    ///    abort. `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as
    ///    `GResource` supports embedding modern image formats just as well. Instead
    ///    of using it, embed a PNG or SVG file in your `GResource`.
    ///
    ///  - `json-stripblanks` which will use the
    ///    [`json-glib-format`](man:json-glib-format(1)) command to strip ignorable
    ///    whitespace from the JSON file. For this to work, the `JSON_GLIB_FORMAT`
    ///    environment variable must be set to the full path to the
    ///    `json-glib-format` executable, or it must be in the `PATH`; otherwise the
    ///    preprocessing step is skipped. In addition, at least version 1.6 of
    ///    `json-glib-format` is required.
    ///
    /// Resource files will be exported in the `GResource` namespace using the
    /// combination of the given `prefix` and the filename from the `file` element.
    /// The `alias` attribute can be used to alter the filename to expose them at a
    /// different location in the resource namespace. Typically, this is used to
    /// include files from a different source directory without exposing the source
    /// directory in the resource namespace, as in the example below.
    ///
    /// Resource bundles are created by the
    /// [`glib-compile-resources`](glib-compile-resources.html) program
    /// which takes an XML file that describes the bundle, and a set of files that
    /// the XML references. These are combined into a binary resource bundle.
    ///
    /// An example resource description:
    /// ```xml
    /// <?xml version="1.0" encoding="UTF-8"?>
    /// <gresources>
    ///   <gresource prefix="/org/gtk/Example">
    ///     <file>data/splashscreen.png</file>
    ///     <file compressed="true">dialog.ui</file>
    ///     <file preprocess="xml-stripblanks">menumarkup.xml</file>
    ///     <file alias="example.css">data/example.css</file>
    ///   </gresource>
    /// </gresources>
    /// ```
    ///
    /// This will create a resource bundle with the following files:
    /// ```text
    /// /org/gtk/Example/data/splashscreen.png
    /// /org/gtk/Example/dialog.ui
    /// /org/gtk/Example/menumarkup.xml
    /// /org/gtk/Example/example.css
    /// ```
    ///
    /// Note that all resources in the process share the same namespace, so use
    /// Java-style path prefixes (like in the above example) to avoid conflicts.
    ///
    /// You can then use [`glib-compile-resources`](glib-compile-resources.html) to
    /// compile the XML to a binary bundle that you can load with
    /// [`load()`][Self::load()]. However, it’s more common to use the
    /// `--generate-source` and `--generate-header` arguments to create a source file
    /// and header to link directly into your application.
    /// This will generate `get_resource()`, `register_resource()` and
    /// `unregister_resource()` functions, prefixed by the `--c-name` argument passed
    /// to [`glib-compile-resources`](glib-compile-resources.html). `get_resource()`
    /// returns the generated `GResource` object. The register and unregister
    /// functions register the resource so its files can be accessed using
    /// [`resources_lookup_data()`][crate::resources_lookup_data()].
    ///
    /// Once a `GResource` has been created and registered all the data in it can be
    /// accessed globally in the process by using API calls like
    /// [`resources_open_stream()`][crate::resources_open_stream()] to stream the data or
    /// [`resources_lookup_data()`][crate::resources_lookup_data()] to get a direct pointer to the data. You can
    /// also use URIs like `resource:///org/gtk/Example/data/splashscreen.png` with
    /// [`File`][crate::File] to access the resource data.
    ///
    /// Some higher-level APIs, such as [`GtkApplication`](https://docs.gtk.org/gtk4/class.Application.html),
    /// will automatically load resources from certain well-known paths in the
    /// resource namespace as a convenience. See the documentation for those APIs
    /// for details.
    ///
    /// There are two forms of the generated source, the default version uses the
    /// compiler support for constructor and destructor functions (where available)
    /// to automatically create and register the `GResource` on startup or library
    /// load time. If you pass `--manual-register`, two functions to
    /// register/unregister the resource are created instead. This requires an
    /// explicit initialization call in your application/library, but it works on all
    /// platforms, even on the minor ones where constructors are not supported.
    /// (Constructor support is available for at least Win32, Mac OS and Linux.)
    ///
    /// Note that resource data can point directly into the data segment of e.g. a
    /// library, so if you are unloading libraries during runtime you need to be very
    /// careful with keeping around pointers to data from a resource, as this goes
    /// away when the library is unloaded. However, in practice this is not generally
    /// a problem, since most resource accesses are for your own resources, and
    /// resource data is often used once, during parsing, and then released.
    ///
    /// # Overlays
    ///
    /// When debugging a program or testing a change to an installed version, it is
    /// often useful to be able to replace resources in the program or library,
    /// without recompiling, for debugging or quick hacking and testing purposes.
    /// Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment
    /// variable to selectively overlay resources with replacements from the
    /// filesystem.  It is a `G_SEARCHPATH_SEPARATOR`-separated list of substitutions
    /// to perform during resource lookups. It is ignored when running in a setuid
    /// process.
    ///
    /// A substitution has the form
    ///
    /// ```text
    /// /org/gtk/libgtk=/home/desrt/gtk-overlay
    /// ```
    ///
    /// The part before the `=` is the resource subpath for which the overlay
    /// applies.  The part after is a filesystem path which contains files and
    /// subdirectories as you would like to be loaded as resources with the
    /// equivalent names.
    ///
    /// In the example above, if an application tried to load a resource with the
    /// resource path `/org/gtk/libgtk/ui/gtkdialog.ui` then `GResource` would check
    /// the filesystem path `/home/desrt/gtk-overlay/ui/gtkdialog.ui`.  If a file was
    /// found there, it would be used instead.  This is an overlay, not an outright
    /// replacement, which means that if a file is not found at that path, the
    /// built-in version will be used instead.  Whiteouts are not currently
    /// supported.
    ///
    /// Substitutions must start with a slash, and must not contain a trailing slash
    /// before the `=`.  The path after the slash should ideally be absolute, but
    /// this is not strictly required.  It is possible to overlay the location of a
    /// single resource with an individual file.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct Resource(Shared<ffi::GResource>);

    match fn {
        ref => |ptr| ffi::g_resource_ref(ptr),
        unref => |ptr| ffi::g_resource_unref(ptr),
        type_ => || ffi::g_resource_get_type(),
    }
}

impl Resource {
    /// Returns all the names of children at the specified @path in the resource.
    ///
    /// The return result is a `NULL` terminated list of strings which should
    /// be released with `strfreev()`.
    ///
    /// If @path is invalid or does not exist in the [`Resource`][crate::Resource],
    /// [`ResourceError::NotFound`][crate::ResourceError::NotFound] will be returned.
    ///
    /// @lookup_flags controls the behaviour of the lookup.
    /// ## `path`
    /// A path name inside the resource
    /// ## `lookup_flags`
    /// A [`ResourceLookupFlags`][crate::ResourceLookupFlags]
    ///
    /// # Returns
    ///
    /// an array of constant strings
    #[doc(alias = "g_resource_enumerate_children")]
    pub fn enumerate_children(
        &self,
        path: &str,
        lookup_flags: ResourceLookupFlags,
    ) -> Result<Vec<glib::GString>, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_resource_enumerate_children(
                self.to_glib_none().0,
                path.to_glib_none().0,
                lookup_flags.into_glib(),
                &mut error,
            );
            if error.is_null() {
                Ok(FromGlibPtrContainer::from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Looks for a file at the specified @path in the resource and
    /// if found returns information about it.
    ///
    /// @lookup_flags controls the behaviour of the lookup.
    ///
    /// The only error this can return is [`ResourceError::NotFound`][crate::ResourceError::NotFound], if @path was
    /// not found in @self.
    /// ## `path`
    /// A path name inside the resource
    /// ## `lookup_flags`
    /// A [`ResourceLookupFlags`][crate::ResourceLookupFlags]
    ///
    /// # Returns
    ///
    /// `TRUE` if the file was found, `FALSE` if there were errors
    ///
    /// ## `size`
    /// a location to place the length of the contents of the file,
    ///    or `NULL` if the length is not needed
    ///
    /// ## `flags`
    /// a location to place the flags about the file,
    ///    or `NULL` if the length is not needed
    #[doc(alias = "g_resource_get_info")]
    #[doc(alias = "get_info")]
    pub fn info(
        &self,
        path: &str,
        lookup_flags: ResourceLookupFlags,
    ) -> Result<(usize, u32), glib::Error> {
        unsafe {
            let mut size = std::mem::MaybeUninit::uninit();
            let mut flags = std::mem::MaybeUninit::uninit();
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_resource_get_info(
                self.to_glib_none().0,
                path.to_glib_none().0,
                lookup_flags.into_glib(),
                size.as_mut_ptr(),
                flags.as_mut_ptr(),
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok((size.assume_init(), flags.assume_init()))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns whether the specified @path in the resource
    /// has children.
    /// ## `path`
    /// A pathname inside the resource
    ///
    /// # Returns
    ///
    /// [`true`] if @path has children
    #[cfg(feature = "v2_84")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_84")))]
    #[doc(alias = "g_resource_has_children")]
    pub fn has_children(&self, path: &str) -> bool {
        unsafe {
            from_glib(ffi::g_resource_has_children(
                self.to_glib_none().0,
                path.to_glib_none().0,
            ))
        }
    }

    /// Looks for a file at the specified @path in the resource and
    /// returns a [`glib::Bytes`][crate::glib::Bytes] that lets you directly access the data in
    /// memory.
    ///
    /// The data is always followed by a zero byte, so you
    /// can safely use the data as a C string. However, that byte
    /// is not included in the size of the [`glib::Bytes`][crate::glib::Bytes].
    ///
    /// For uncompressed resource files this is a pointer directly into
    /// the resource bundle, which is typically in some read-only data section
    /// in the program binary. For compressed files, memory is allocated on
    /// the heap and the data is automatically uncompressed.
    ///
    /// @lookup_flags controls the behaviour of the lookup.
    ///
    /// This can return error [`ResourceError::NotFound`][crate::ResourceError::NotFound] if @path was not found in
    /// @self, or [`ResourceError::Internal`][crate::ResourceError::Internal] if decompression of a compressed
    /// resource failed.
    /// ## `path`
    /// A path name inside the resource
    /// ## `lookup_flags`
    /// A [`ResourceLookupFlags`][crate::ResourceLookupFlags]
    ///
    /// # Returns
    ///
    /// [`glib::Bytes`][crate::glib::Bytes] or `NULL` on error
    #[doc(alias = "g_resource_lookup_data")]
    pub fn lookup_data(
        &self,
        path: &str,
        lookup_flags: ResourceLookupFlags,
    ) -> Result<glib::Bytes, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_resource_lookup_data(
                self.to_glib_none().0,
                path.to_glib_none().0,
                lookup_flags.into_glib(),
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Looks for a file at the specified @path in the resource and
    /// returns a [`InputStream`][crate::InputStream] that lets you read the data.
    ///
    /// @lookup_flags controls the behaviour of the lookup.
    ///
    /// The only error this can return is [`ResourceError::NotFound`][crate::ResourceError::NotFound], if @path was
    /// not found in @self.
    /// ## `path`
    /// A path name inside the resource
    /// ## `lookup_flags`
    /// A [`ResourceLookupFlags`][crate::ResourceLookupFlags]
    ///
    /// # Returns
    ///
    /// [`InputStream`][crate::InputStream] or `NULL` on error
    #[doc(alias = "g_resource_open_stream")]
    pub fn open_stream(
        &self,
        path: &str,
        lookup_flags: ResourceLookupFlags,
    ) -> Result<InputStream, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_resource_open_stream(
                self.to_glib_none().0,
                path.to_glib_none().0,
                lookup_flags.into_glib(),
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Loads a binary resource bundle and creates a [`Resource`][crate::Resource]
    /// representation of it, allowing you to query it for data.
    ///
    /// If you want to use this resource in the global resource namespace you need
    /// to register it with [`resources_register()`][crate::resources_register()].
    ///
    /// If @filename is empty or the data in it is corrupt,
    /// [`ResourceError::Internal`][crate::ResourceError::Internal] will be returned. If @filename doesn’t exist, or
    /// there is an error in reading it, an error from `GLib::MappedFile::new()`
    /// will be returned.
    /// ## `filename`
    /// the path of a filename to load, in the GLib filename encoding
    ///
    /// # Returns
    ///
    /// a new [`Resource`][crate::Resource], or `NULL` on error
    #[doc(alias = "g_resource_load")]
    pub fn load(filename: impl AsRef<std::path::Path>) -> Result<Resource, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_resource_load(filename.as_ref().to_glib_none().0, &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}