gstreamer/auto/

registry.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// from gst-gir-files (https://gitlab.freedesktop.org/gstreamer/gir-files-rs.git)
// DO NOT EDIT

use crate::{Object, Plugin, PluginFeature, ffi};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    ///
    ///
    /// The [`Registry`][crate::Registry] object is a list of plugins and some functions for dealing
    /// with them. Each [`Plugin`][crate::Plugin] is matched 1-1 with a file on disk, and may or may
    /// not be loaded at a given time.
    ///
    /// The primary source, at all times, of plugin information is each plugin file
    /// itself. Thus, if an application wants information about a particular plugin,
    /// or wants to search for a feature that satisfies given criteria, the primary
    /// means of doing so is to load every plugin and look at the resulting
    /// information that is gathered in the default registry. Clearly, this is a time
    /// consuming process, so we cache information in the registry file. The format
    /// and location of the cache file is internal to gstreamer.
    ///
    /// On startup, plugins are searched for in the plugin search path. The following
    /// locations are checked in this order:
    ///
    /// * location from --gst-plugin-path commandline option.
    /// * the GST_PLUGIN_PATH environment variable.
    /// * the GST_PLUGIN_SYSTEM_PATH environment variable.
    /// * default locations (if GST_PLUGIN_SYSTEM_PATH is not set).
    ///  Those default locations are:
    ///  `$XDG_DATA_HOME/gstreamer-$GST_API_VERSION/plugins/`
    ///  and `$prefix/libs/gstreamer-$GST_API_VERSION/`.
    ///  [$XDG_DATA_HOME](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) defaults to
    ///  `$HOME/.local/share`.
    ///
    /// The registry cache file is loaded from
    /// `$XDG_CACHE_HOME/gstreamer-$GST_API_VERSION/registry-$ARCH.bin`
    /// (where $XDG_CACHE_HOME defaults to `$HOME/.cache`) or the file listed in the `GST_REGISTRY`
    /// env var. One reason to change the registry location is for testing.
    ///
    /// For each plugin that is found in the plugin search path, there could be 3
    /// possibilities for cached information:
    ///
    ///  * the cache may not contain information about a given file.
    ///  * the cache may have stale information.
    ///  * the cache may have current information.
    ///
    /// In the first two cases, the plugin is loaded and the cache updated. In
    /// addition to these cases, the cache may have entries for plugins that are not
    /// relevant to the current process. These are marked as not available to the
    /// current process. If the cache is updated for whatever reason, it is marked
    /// dirty.
    ///
    /// A dirty cache is written out at the end of initialization. Each entry is
    /// checked to make sure the information is minimally valid. If not, the entry is
    /// simply dropped.
    ///
    /// ## Implementation notes:
    ///
    /// The "cache" and "registry" are different concepts and can represent
    /// different sets of plugins. For various reasons, at init time, the cache is
    /// stored in the default registry, and plugins not relevant to the current
    /// process are marked with the [`PluginFlags::CACHED`][crate::PluginFlags::CACHED] bit. These plugins are
    /// removed at the end of initialization.
    ///
    /// ## Signals
    ///
    ///
    /// #### `feature-added`
    ///  Signals that a feature has been added to the registry (possibly
    /// replacing a previously-added one by the same name)
    ///
    ///
    ///
    ///
    /// #### `plugin-added`
    ///  Signals that a plugin has been added to the registry (possibly
    /// replacing a previously-added one by the same name)
    ///
    ///
    /// <details><summary><h4>Object</h4></summary>
    ///
    ///
    /// #### `deep-notify`
    ///  The deep notify signal is used to be notified of property changes. It is
    /// typically attached to the toplevel bin to receive notifications from all
    /// the elements contained in that bin.
    ///
    /// Detailed
    /// </details>
    ///
    /// # Implements
    ///
    /// [`GstObjectExt`][trait@crate::prelude::GstObjectExt], [`trait@glib::ObjectExt`], [`GstObjectExtManual`][trait@crate::prelude::GstObjectExtManual]
    #[doc(alias = "GstRegistry")]
    pub struct Registry(Object<ffi::GstRegistry, ffi::GstRegistryClass>) @extends Object;

    match fn {
        type_ => || ffi::gst_registry_get_type(),
    }
}

impl Registry {
    /// Add the feature to the registry. The feature-added signal will be emitted.
    ///
    /// `feature`'s reference count will be incremented, and any floating
    /// reference will be removed (see `gst_object_ref_sink()`)
    /// ## `feature`
    /// the feature to add
    ///
    /// # Returns
    ///
    /// [`true`] on success.
    ///
    /// MT safe.
    #[doc(alias = "gst_registry_add_feature")]
    pub fn add_feature(
        &self,
        feature: &impl IsA<PluginFeature>,
    ) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_registry_add_feature(
                    self.to_glib_none().0,
                    feature.as_ref().to_glib_none().0
                ),
                "Failed to add feature"
            )
        }
    }

    /// Add the plugin to the registry. The plugin-added signal will be emitted.
    ///
    /// `plugin`'s reference count will be incremented, and any floating
    /// reference will be removed (see `gst_object_ref_sink()`)
    /// ## `plugin`
    /// the plugin to add
    ///
    /// # Returns
    ///
    /// [`true`] on success.
    ///
    /// MT safe.
    #[doc(alias = "gst_registry_add_plugin")]
    pub fn add_plugin(&self, plugin: &Plugin) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_registry_add_plugin(self.to_glib_none().0, plugin.to_glib_none().0),
                "Failed to add plugin"
            )
        }
    }

    /// Checks whether a plugin feature by the given name exists in
    /// `self` and whether its version is at least the
    /// version required.
    /// ## `feature_name`
    /// the name of the feature (e.g. "oggdemux")
    /// ## `min_major`
    /// the minimum major version number
    /// ## `min_minor`
    /// the minimum minor version number
    /// ## `min_micro`
    /// the minimum micro version number
    ///
    /// # Returns
    ///
    /// [`true`] if the feature could be found and the version is
    /// the same as the required version or newer, and [`false`] otherwise.
    #[doc(alias = "gst_registry_check_feature_version")]
    pub fn check_feature_version(
        &self,
        feature_name: &str,
        min_major: u32,
        min_minor: u32,
        min_micro: u32,
    ) -> bool {
        unsafe {
            from_glib(ffi::gst_registry_check_feature_version(
                self.to_glib_none().0,
                feature_name.to_glib_none().0,
                min_major,
                min_minor,
                min_micro,
            ))
        }
    }

    /// Find the pluginfeature with the given name and type in the registry.
    /// ## `name`
    /// the pluginfeature name to find
    /// ## `type_`
    /// the pluginfeature type to find
    ///
    /// # Returns
    ///
    /// the pluginfeature with the
    ///  given name and type or [`None`] if the plugin was not
    ///  found. `gst_object_unref()` after usage.
    ///
    /// MT safe.
    #[doc(alias = "gst_registry_find_feature")]
    pub fn find_feature(&self, name: &str, type_: glib::types::Type) -> Option<PluginFeature> {
        unsafe {
            from_glib_full(ffi::gst_registry_find_feature(
                self.to_glib_none().0,
                name.to_glib_none().0,
                type_.into_glib(),
            ))
        }
    }

    /// Find the plugin with the given name in the registry.
    /// The plugin will be reffed; caller is responsible for unreffing.
    /// ## `name`
    /// the plugin name to find
    ///
    /// # Returns
    ///
    /// the plugin with the given name
    ///  or [`None`] if the plugin was not found. `gst_object_unref()` after
    ///  usage.
    ///
    /// MT safe.
    #[doc(alias = "gst_registry_find_plugin")]
    pub fn find_plugin(&self, name: &str) -> Option<Plugin> {
        unsafe {
            from_glib_full(ffi::gst_registry_find_plugin(
                self.to_glib_none().0,
                name.to_glib_none().0,
            ))
        }
    }

    /// Returns the registry's feature list cookie. This changes
    /// every time a feature is added or removed from the registry.
    ///
    /// # Returns
    ///
    /// the feature list cookie.
    #[doc(alias = "gst_registry_get_feature_list_cookie")]
    #[doc(alias = "get_feature_list_cookie")]
    pub fn feature_list_cookie(&self) -> u32 {
        unsafe { ffi::gst_registry_get_feature_list_cookie(self.to_glib_none().0) }
    }

    /// Look up a plugin in the given registry with the given filename.
    /// If found, plugin is reffed.
    /// ## `filename`
    /// the name of the file to look up
    ///
    /// # Returns
    ///
    /// the [`Plugin`][crate::Plugin] if found, or
    ///  [`None`] if not. `gst_object_unref()` after usage.
    #[doc(alias = "gst_registry_lookup")]
    pub fn lookup(&self, filename: &str) -> Option<Plugin> {
        unsafe {
            from_glib_full(ffi::gst_registry_lookup(
                self.to_glib_none().0,
                filename.to_glib_none().0,
            ))
        }
    }

    /// Find a [`PluginFeature`][crate::PluginFeature] with `name` in `self`.
    /// ## `name`
    /// a [`PluginFeature`][crate::PluginFeature] name
    ///
    /// # Returns
    ///
    /// a [`PluginFeature`][crate::PluginFeature] with its refcount incremented,
    ///  use `gst_object_unref()` after usage.
    ///
    /// MT safe.
    #[doc(alias = "gst_registry_lookup_feature")]
    pub fn lookup_feature(&self, name: &str) -> Option<PluginFeature> {
        unsafe {
            from_glib_full(ffi::gst_registry_lookup_feature(
                self.to_glib_none().0,
                name.to_glib_none().0,
            ))
        }
    }

    /// Remove the feature from the registry.
    ///
    /// MT safe.
    /// ## `feature`
    /// the feature to remove
    #[doc(alias = "gst_registry_remove_feature")]
    pub fn remove_feature(&self, feature: &impl IsA<PluginFeature>) {
        unsafe {
            ffi::gst_registry_remove_feature(
                self.to_glib_none().0,
                feature.as_ref().to_glib_none().0,
            );
        }
    }

    /// Remove the plugin from the registry.
    ///
    /// MT safe.
    /// ## `plugin`
    /// the plugin to remove
    #[doc(alias = "gst_registry_remove_plugin")]
    pub fn remove_plugin(&self, plugin: &Plugin) {
        unsafe {
            ffi::gst_registry_remove_plugin(self.to_glib_none().0, plugin.to_glib_none().0);
        }
    }

    /// Scan the given path for plugins to add to the registry. The syntax of the
    /// path is specific to the registry.
    /// ## `path`
    /// the path to scan
    ///
    /// # Returns
    ///
    /// [`true`] if registry changed
    #[doc(alias = "gst_registry_scan_path")]
    pub fn scan_path(&self, path: impl AsRef<std::path::Path>) -> bool {
        unsafe {
            from_glib(ffi::gst_registry_scan_path(
                self.to_glib_none().0,
                path.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Retrieves the singleton plugin registry. The caller does not own a
    /// reference on the registry, as it is alive as long as GStreamer is
    /// initialized.
    ///
    /// # Returns
    ///
    /// the [`Registry`][crate::Registry].
    #[doc(alias = "gst_registry_get")]
    pub fn get() -> Registry {
        assert_initialized_main_thread!();
        unsafe { from_glib_none(ffi::gst_registry_get()) }
    }

    /// Signals that a feature has been added to the registry (possibly
    /// replacing a previously-added one by the same name)
    /// ## `feature`
    /// the feature that has been added
    #[doc(alias = "feature-added")]
    pub fn connect_feature_added<F: Fn(&Self, &PluginFeature) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn feature_added_trampoline<
            F: Fn(&Registry, &PluginFeature) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstRegistry,
            feature: *mut ffi::GstPluginFeature,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(&from_glib_borrow(this), &from_glib_borrow(feature))
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"feature-added".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    feature_added_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Signals that a plugin has been added to the registry (possibly
    /// replacing a previously-added one by the same name)
    /// ## `plugin`
    /// the plugin that has been added
    #[doc(alias = "plugin-added")]
    pub fn connect_plugin_added<F: Fn(&Self, &Plugin) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn plugin_added_trampoline<
            F: Fn(&Registry, &Plugin) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstRegistry,
            plugin: *mut ffi::GstPlugin,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(&from_glib_borrow(this), &from_glib_borrow(plugin))
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"plugin-added".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    plugin_added_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

unsafe impl Send for Registry {}
unsafe impl Sync for Registry {}