gstreamer/auto/

plugin.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

#[cfg(feature = "v1_30")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_30")))]
use crate::Registry;
use crate::{Object, PluginDependencyFlags, Structure, ffi};
use glib::translate::*;

glib::wrapper! {
    /// GStreamer is extensible, so [`Element`][crate::Element] instances can be loaded at runtime.
    /// A plugin system can provide one or more of the basic GStreamer
    /// [`PluginFeature`][crate::PluginFeature] subclasses.
    ///
    /// A plugin should export a symbol `gst_plugin_desc` that is a
    /// struct of type `GstPluginDesc`.
    /// the plugin loader will check the version of the core library the plugin was
    /// linked against and will create a new [`Plugin`][crate::Plugin]. It will then call the
    /// `GstPluginInitFunc` function that was provided in the
    /// `gst_plugin_desc`.
    ///
    /// Once you have a handle to a [`Plugin`][crate::Plugin] (e.g. from the [`Registry`][crate::Registry]), you
    /// can add any object that subclasses [`PluginFeature`][crate::PluginFeature].
    ///
    /// Usually plugins are always automatically loaded so you don't need to call
    /// [`load()`][Self::load()] explicitly to bring it into memory. There are options to
    /// statically link plugins to an app or even use GStreamer without a plugin
    /// repository in which case [`load()`][Self::load()] can be needed to bring the plugin
    /// into memory.
    ///
    /// # Implements
    ///
    /// [`GstObjectExt`][trait@crate::prelude::GstObjectExt], [`trait@glib::ObjectExt`], [`GstObjectExtManual`][trait@crate::prelude::GstObjectExtManual]
    #[doc(alias = "GstPlugin")]
    pub struct Plugin(Object<ffi::GstPlugin, ffi::GstPluginClass>) @extends Object;

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

impl Plugin {
    /// Make GStreamer aware of external dependencies which affect the feature
    /// set of this plugin (ie. the elements or typefinders associated with it).
    ///
    /// GStreamer will re-inspect plugins with external dependencies whenever any
    /// of the external dependencies change. This is useful for plugins which wrap
    /// other plugin systems, e.g. a plugin which wraps a plugin-based visualisation
    /// library and makes visualisations available as GStreamer elements, or a
    /// codec loader which exposes elements and/or caps dependent on what external
    /// codec libraries are currently installed.
    ///
    /// It is an error to register dependencies for any plugin that has been marked
    /// as only have a static set of features via [`set_static_features_flag()`][Self::set_static_features_flag()]
    /// ## `env_vars`
    /// [`None`]-terminated array of environment variables affecting the
    ///  feature set of the plugin (e.g. an environment variable containing
    ///  paths where to look for additional modules/plugins of a library),
    ///  or [`None`]. Environment variable names may be followed by a path component
    ///  which will be added to the content of the environment variable, e.g.
    ///  "HOME/.mystuff/plugins".
    /// ## `paths`
    /// [`None`]-terminated array of directories/paths where dependent files
    ///  may be, or [`None`].
    /// ## `names`
    /// [`None`]-terminated array of file names (or file name suffixes,
    ///  depending on `flags`) to be used in combination with the paths from
    ///  `paths` and/or the paths extracted from the environment variables in
    ///  `env_vars`, or [`None`].
    /// ## `flags`
    /// optional flags, or `GST_PLUGIN_DEPENDENCY_FLAG_NONE`
    #[doc(alias = "gst_plugin_add_dependency")]
    pub fn add_dependency(
        &self,
        env_vars: &[&str],
        paths: &[&str],
        names: &[&str],
        flags: PluginDependencyFlags,
    ) {
        unsafe {
            ffi::gst_plugin_add_dependency(
                self.to_glib_none().0,
                env_vars.to_glib_none().0,
                paths.to_glib_none().0,
                names.to_glib_none().0,
                flags.into_glib(),
            );
        }
    }

    /// Make GStreamer aware of external dependencies which affect the feature
    /// set of this plugin (ie. the elements or typefinders associated with it).
    ///
    /// GStreamer will re-inspect plugins with external dependencies whenever any
    /// of the external dependencies change. This is useful for plugins which wrap
    /// other plugin systems, e.g. a plugin which wraps a plugin-based visualisation
    /// library and makes visualisations available as GStreamer elements, or a
    /// codec loader which exposes elements and/or caps dependent on what external
    /// codec libraries are currently installed.
    ///
    /// Convenience wrapper function for [`add_dependency()`][Self::add_dependency()] which
    /// takes simple strings as arguments instead of string arrays, with multiple
    /// arguments separated by predefined delimiters (see above).
    ///
    /// It is an error to register dependencies for any plugin that has been marked
    /// as only have a static set of features via [`set_static_features_flag()`][Self::set_static_features_flag()].
    /// ## `env_vars`
    /// one or more environment variables (separated by ':', ';' or ','),
    ///  or [`None`]. Environment variable names may be followed by a path component
    ///  which will be added to the content of the environment variable, e.g.
    ///  "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH"
    /// ## `paths`
    /// one or more directory paths (separated by ':' or ';' or ','),
    ///  or [`None`]. Example: "/usr/lib/mystuff/plugins"
    /// ## `names`
    /// one or more file names or file name suffixes (separated by commas),
    ///  or [`None`]
    /// ## `flags`
    /// optional flags, or `GST_PLUGIN_DEPENDENCY_FLAG_NONE`
    #[doc(alias = "gst_plugin_add_dependency_simple")]
    pub fn add_dependency_simple(
        &self,
        env_vars: Option<&str>,
        paths: Option<&str>,
        names: Option<&str>,
        flags: PluginDependencyFlags,
    ) {
        unsafe {
            ffi::gst_plugin_add_dependency_simple(
                self.to_glib_none().0,
                env_vars.to_glib_none().0,
                paths.to_glib_none().0,
                names.to_glib_none().0,
                flags.into_glib(),
            );
        }
    }

    /// ## `message`
    /// the status error message
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_plugin_add_status_error")]
    pub fn add_status_error(&self, message: &str) {
        unsafe {
            ffi::gst_plugin_add_status_error(self.to_glib_none().0, message.to_glib_none().0);
        }
    }

    /// ## `message`
    /// the status info message
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_plugin_add_status_info")]
    pub fn add_status_info(&self, message: &str) {
        unsafe {
            ffi::gst_plugin_add_status_info(self.to_glib_none().0, message.to_glib_none().0);
        }
    }

    /// ## `message`
    /// the status warning message
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_plugin_add_status_warning")]
    pub fn add_status_warning(&self, message: &str) {
        unsafe {
            ffi::gst_plugin_add_status_warning(self.to_glib_none().0, message.to_glib_none().0);
        }
    }

    /// Get the long descriptive name of the plugin
    ///
    /// # Returns
    ///
    /// the long name of the plugin
    #[doc(alias = "gst_plugin_get_description")]
    #[doc(alias = "get_description")]
    pub fn description(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_description(self.to_glib_none().0)) }
    }

    /// get the filename of the plugin
    ///
    /// # Returns
    ///
    /// the filename of the plugin
    #[doc(alias = "gst_plugin_get_filename")]
    #[doc(alias = "get_filename")]
    pub fn filename(&self) -> Option<std::path::PathBuf> {
        unsafe { from_glib_none(ffi::gst_plugin_get_filename(self.to_glib_none().0)) }
    }

    /// get the license of the plugin
    ///
    /// # Returns
    ///
    /// the license of the plugin
    #[doc(alias = "gst_plugin_get_license")]
    #[doc(alias = "get_license")]
    pub fn license(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_license(self.to_glib_none().0)) }
    }

    /// Get the short name of the plugin
    ///
    /// # Returns
    ///
    /// the name of the plugin
    #[doc(alias = "gst_plugin_get_name")]
    #[doc(alias = "get_name")]
    pub fn plugin_name(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_name(self.to_glib_none().0)) }
    }

    /// get the URL where the plugin comes from
    ///
    /// # Returns
    ///
    /// the origin of the plugin
    #[doc(alias = "gst_plugin_get_origin")]
    #[doc(alias = "get_origin")]
    pub fn origin(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_origin(self.to_glib_none().0)) }
    }

    /// get the package the plugin belongs to.
    ///
    /// # Returns
    ///
    /// the package of the plugin
    #[doc(alias = "gst_plugin_get_package")]
    #[doc(alias = "get_package")]
    pub fn package(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_package(self.to_glib_none().0)) }
    }

    /// Get the [`Registry`][crate::Registry] this plugin belongs to, for use when registering
    /// associated [`PluginFeature`][crate::PluginFeature] during plugin registration. Usually
    /// this is just the default registry, but may differ during pre-built
    /// registry creation. If passed NULL, returns the default registry
    ///
    /// # Returns
    ///
    /// The [`Registry`][crate::Registry] to use for plugin feature registration
    #[cfg(feature = "v1_30")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_30")))]
    #[doc(alias = "gst_plugin_get_registry")]
    #[doc(alias = "get_registry")]
    pub fn registry(&self) -> Registry {
        unsafe { from_glib_none(ffi::gst_plugin_get_registry(self.to_glib_none().0)) }
    }

    /// Get the release date (and possibly time) in form of a string, if available.
    ///
    /// For normal GStreamer plugin releases this will usually just be a date in
    /// the form of "YYYY-MM-DD", while pre-releases and builds from git may contain
    /// a time component after the date as well, in which case the string will be
    /// formatted like "YYYY-MM-DDTHH:MMZ" (e.g. "2012-04-30T09:30Z").
    ///
    /// There may be plugins that do not have a valid release date set on them.
    ///
    /// # Returns
    ///
    /// the date string of the plugin, or [`None`] if not
    /// available.
    #[doc(alias = "gst_plugin_get_release_date_string")]
    #[doc(alias = "get_release_date_string")]
    pub fn release_date_string(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::gst_plugin_get_release_date_string(
                self.to_glib_none().0,
            ))
        }
    }

    /// get the source module the plugin belongs to.
    ///
    /// # Returns
    ///
    /// the source of the plugin
    #[doc(alias = "gst_plugin_get_source")]
    #[doc(alias = "get_source")]
    pub fn source(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_source(self.to_glib_none().0)) }
    }

    ///
    /// # Returns
    ///
    /// an array of plugin status error messages, or NULL
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_plugin_get_status_errors")]
    #[doc(alias = "get_status_errors")]
    pub fn status_errors(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::gst_plugin_get_status_errors(
                self.to_glib_none().0,
            ))
        }
    }

    ///
    /// # Returns
    ///
    /// an array of plugin status info messages, or NULL
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_plugin_get_status_infos")]
    #[doc(alias = "get_status_infos")]
    pub fn status_infos(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::gst_plugin_get_status_infos(
                self.to_glib_none().0,
            ))
        }
    }

    ///
    /// # Returns
    ///
    /// an array of plugin status warning messages, or NULL
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_plugin_get_status_warnings")]
    #[doc(alias = "get_status_warnings")]
    pub fn status_warnings(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::gst_plugin_get_status_warnings(
                self.to_glib_none().0,
            ))
        }
    }

    /// get the version of the plugin
    ///
    /// # Returns
    ///
    /// the version of the plugin
    #[doc(alias = "gst_plugin_get_version")]
    #[doc(alias = "get_version")]
    pub fn version(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gst_plugin_get_version(self.to_glib_none().0)) }
    }

    /// queries if the plugin is loaded into memory
    ///
    /// # Returns
    ///
    /// [`true`] is loaded, [`false`] otherwise
    #[doc(alias = "gst_plugin_is_loaded")]
    pub fn is_loaded(&self) -> bool {
        unsafe { from_glib(ffi::gst_plugin_is_loaded(self.to_glib_none().0)) }
    }

    /// Loads `self`. Note that the *return value* is the loaded plugin; `self` is
    /// untouched. The normal use pattern of this function goes like this:
    ///
    ///
    /// ```text
    /// GstPlugin *loaded_plugin;
    /// loaded_plugin = gst_plugin_load (plugin);
    /// // presumably, we're no longer interested in the potentially-unloaded plugin
    /// gst_object_unref (plugin);
    /// plugin = loaded_plugin;
    /// ```
    ///
    /// # Returns
    ///
    /// a reference to a loaded plugin, or
    /// [`None`] on error.
    #[doc(alias = "gst_plugin_load")]
    pub fn load(&self) -> Result<Plugin, glib::BoolError> {
        unsafe {
            Option::<_>::from_glib_full(ffi::gst_plugin_load(self.to_glib_none().0))
                .ok_or_else(|| glib::bool_error!("Failed to load plugin"))
        }
    }

    /// Adds plugin specific data to cache. Passes the ownership of the structure to
    /// the `self`.
    ///
    /// The cache is flushed every time the registry is rebuilt.
    /// ## `cache_data`
    /// a structure containing the data to cache
    #[doc(alias = "gst_plugin_set_cache_data")]
    pub fn set_cache_data(&self, cache_data: Structure) {
        unsafe {
            ffi::gst_plugin_set_cache_data(self.to_glib_none().0, cache_data.into_glib_ptr());
        }
    }

    /// Marks this plugin as having no external dependencies, and
    /// a static set of plugin features, rendering it suitable
    /// for inclusion in a static build-time registry. Shipping a static
    /// build-time registry speeds up application startup by avoiding
    /// scanning of these plugins at run-time.
    ///
    /// It is an error to call this function after any [`add_dependency()`][Self::add_dependency()]
    /// or [`add_dependency_simple()`][Self::add_dependency_simple()] call, or to call those functions
    /// once this flag is set.
    #[cfg(feature = "v1_30")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_30")))]
    #[doc(alias = "gst_plugin_set_static_features_flag")]
    pub fn set_static_features_flag(&self) {
        unsafe {
            ffi::gst_plugin_set_static_features_flag(self.to_glib_none().0);
        }
    }

    /// Load the named plugin. Refs the plugin.
    /// ## `name`
    /// name of plugin to load
    ///
    /// # Returns
    ///
    /// a reference to a loaded plugin, or
    /// [`None`] on error.
    #[doc(alias = "gst_plugin_load_by_name")]
    pub fn load_by_name(name: &str) -> Result<Plugin, glib::BoolError> {
        assert_initialized_main_thread!();
        unsafe {
            Option::<_>::from_glib_full(ffi::gst_plugin_load_by_name(name.to_glib_none().0))
                .ok_or_else(|| glib::bool_error!("Failed to load plugin"))
        }
    }

    /// Loads the given plugin and refs it. Caller needs to unref after use.
    /// ## `filename`
    /// the plugin filename to load
    ///
    /// # Returns
    ///
    /// a reference to the existing loaded GstPlugin, a
    /// reference to the newly-loaded GstPlugin, or [`None`] if an error occurred.
    #[doc(alias = "gst_plugin_load_file")]
    pub fn load_file(filename: impl AsRef<std::path::Path>) -> Result<Plugin, glib::Error> {
        assert_initialized_main_thread!();
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gst_plugin_load_file(filename.as_ref().to_glib_none().0, &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}

impl std::fmt::Display for Plugin {
    #[inline]
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        f.write_str(&self.plugin_name())
    }
}

unsafe impl Send for Plugin {}
unsafe impl Sync for Plugin {}