gstreamer_pbutils/auto/

discoverer.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::{ffi, DiscovererInfo};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// The [`Discoverer`][crate::Discoverer] is a utility object which allows to get as much
    /// information as possible from one or many URIs.
    ///
    /// It provides two APIs, allowing usage in blocking or non-blocking mode.
    ///
    /// The blocking mode just requires calling [`discover_uri()`][Self::discover_uri()]
    /// with the URI one wishes to discover.
    ///
    /// The non-blocking mode requires a running [`glib::MainLoop`][crate::glib::MainLoop] iterating a
    /// [`glib::MainContext`][crate::glib::MainContext], where one connects to the various signals, appends the
    /// URIs to be processed (through [`discover_uri_async()`][Self::discover_uri_async()]) and then
    /// asks for the discovery to begin (through [`start()`][Self::start()]).
    /// By default this will use the GLib default main context unless you have
    /// set a custom context using [`glib::MainContext::push_thread_default()`][crate::glib::MainContext::push_thread_default()].
    ///
    /// All the information is returned in a [`DiscovererInfo`][crate::DiscovererInfo] structure.
    ///
    /// ## Properties
    ///
    ///
    /// #### `timeout`
    ///  The duration (in nanoseconds) after which the discovery of an individual
    /// URI will timeout.
    ///
    /// If the discovery of a URI times out, the [`DiscovererResult::Timeout`][crate::DiscovererResult::Timeout] will be
    /// set on the result flags.
    ///
    /// Readable | Writeable | Construct
    ///
    ///
    /// #### `use-cache`
    ///  Readable | Writeable | Construct
    ///
    /// ## Signals
    ///
    ///
    /// #### `discovered`
    ///  Will be emitted in async mode when all information on a URI could be
    /// discovered, or an error occurred.
    ///
    /// When an error occurs, `info` might still contain some partial information,
    /// depending on the circumstances of the error.
    ///
    ///
    ///
    ///
    /// #### `finished`
    ///  Will be emitted in async mode when all pending URIs have been processed.
    ///
    ///
    ///
    ///
    /// #### `load-serialized-info`
    ///  Retrieves information about a URI from and external source of information,
    /// like a cache file. This is used by the discoverer to speed up the
    /// discovery.
    ///
    ///
    ///
    ///
    /// #### `source-setup`
    ///  This signal is emitted after the source element has been created for, so
    /// the URI being discovered, so it can be configured by setting additional
    /// properties (e.g. set a proxy server for an http source, or set the device
    /// and read speed for an audio cd source).
    ///
    /// This signal is usually emitted from the context of a GStreamer streaming
    /// thread.
    ///
    ///
    ///
    ///
    /// #### `starting`
    ///  Will be emitted when the discover starts analyzing the pending URIs
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`]
    #[doc(alias = "GstDiscoverer")]
    pub struct Discoverer(Object<ffi::GstDiscoverer, ffi::GstDiscovererClass>);

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

impl Discoverer {
    /// Creates a new [`Discoverer`][crate::Discoverer] with the provided timeout.
    /// ## `timeout`
    /// timeout per file, in nanoseconds. Allowed are values between
    ///  one second (`GST_SECOND`) and one hour (3600 * `GST_SECOND`)
    ///
    /// # Returns
    ///
    /// The new [`Discoverer`][crate::Discoverer].
    /// If an error occurred when creating the discoverer, `err` will be set
    /// accordingly and [`None`] will be returned. If `err` is set, the caller must
    /// free it when no longer needed using `g_error_free()`.
    #[doc(alias = "gst_discoverer_new")]
    pub fn new(timeout: gst::ClockTime) -> Result<Discoverer, glib::Error> {
        assert_initialized_main_thread!();
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gst_discoverer_new(timeout.into_glib(), &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Synchronously discovers the given `uri`.
    ///
    /// A copy of `uri` will be made internally, so the caller can safely `g_free()`
    /// afterwards.
    /// ## `uri`
    /// The URI to run on.
    ///
    /// # Returns
    ///
    /// the result of the scanning. Can be [`None`] if an
    /// error occurred.
    #[doc(alias = "gst_discoverer_discover_uri")]
    pub fn discover_uri(&self, uri: &str) -> Result<DiscovererInfo, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gst_discoverer_discover_uri(
                self.to_glib_none().0,
                uri.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Appends the given `uri` to the list of URIs to discoverer. The actual
    /// discovery of the `uri` will only take place if [`start()`][Self::start()] has
    /// been called.
    ///
    /// A copy of `uri` will be made internally, so the caller can safely `g_free()`
    /// afterwards.
    /// ## `uri`
    /// the URI to add.
    ///
    /// # Returns
    ///
    /// [`true`] if the `uri` was successfully appended to the list of pending
    /// uris, else [`false`]
    #[doc(alias = "gst_discoverer_discover_uri_async")]
    pub fn discover_uri_async(&self, uri: &str) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_discoverer_discover_uri_async(self.to_glib_none().0, uri.to_glib_none().0),
                "Failed to add URI to list of discovers"
            )
        }
    }

    /// Allow asynchronous discovering of URIs to take place.
    /// A [`glib::MainLoop`][crate::glib::MainLoop] must be available for [`Discoverer`][crate::Discoverer] to properly work in
    /// asynchronous mode.
    #[doc(alias = "gst_discoverer_start")]
    pub fn start(&self) {
        unsafe {
            ffi::gst_discoverer_start(self.to_glib_none().0);
        }
    }

    /// Stop the discovery of any pending URIs and clears the list of
    /// pending URIS (if any).
    #[doc(alias = "gst_discoverer_stop")]
    pub fn stop(&self) {
        unsafe {
            ffi::gst_discoverer_stop(self.to_glib_none().0);
        }
    }

    #[cfg(feature = "v1_16")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_16")))]
    #[doc(alias = "use-cache")]
    pub fn uses_cache(&self) -> bool {
        ObjectExt::property(self, "use-cache")
    }

    #[cfg(feature = "v1_16")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_16")))]
    #[doc(alias = "use-cache")]
    pub fn set_use_cache(&self, use_cache: bool) {
        ObjectExt::set_property(self, "use-cache", use_cache)
    }

    /// Will be emitted in async mode when all information on a URI could be
    /// discovered, or an error occurred.
    ///
    /// When an error occurs, `info` might still contain some partial information,
    /// depending on the circumstances of the error.
    /// ## `info`
    /// the results [`DiscovererInfo`][crate::DiscovererInfo]
    /// ## `error`
    /// [`glib::Error`][crate::glib::Error], which will be non-NULL
    ///  if an error occurred during
    ///  discovery. You must not free
    ///  this [`glib::Error`][crate::glib::Error], it will be freed by
    ///  the discoverer.
    #[doc(alias = "discovered")]
    pub fn connect_discovered<
        F: Fn(&Self, &DiscovererInfo, Option<&glib::Error>) + Send + Sync + 'static,
    >(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn discovered_trampoline<
            F: Fn(&Discoverer, &DiscovererInfo, Option<&glib::Error>) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstDiscoverer,
            info: *mut ffi::GstDiscovererInfo,
            error: *mut glib::ffi::GError,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                &from_glib_borrow(this),
                &from_glib_borrow(info),
                Option::<glib::Error>::from_glib_borrow(error)
                    .as_ref()
                    .as_ref(),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"discovered".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    discovered_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Will be emitted in async mode when all pending URIs have been processed.
    #[doc(alias = "finished")]
    pub fn connect_finished<F: Fn(&Self) + Send + Sync + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn finished_trampoline<F: Fn(&Discoverer) + Send + Sync + 'static>(
            this: *mut ffi::GstDiscoverer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"finished".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    finished_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Retrieves information about a URI from and external source of information,
    /// like a cache file. This is used by the discoverer to speed up the
    /// discovery.
    /// ## `uri`
    /// THe URI to load the serialized info for
    ///
    /// # Returns
    ///
    /// The [`DiscovererInfo`][crate::DiscovererInfo] representing
    /// `uri`, or [`None`] if no information
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "load-serialized-info")]
    pub fn connect_load_serialized_info<
        F: Fn(&Self, &str) -> Option<DiscovererInfo> + Send + Sync + 'static,
    >(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn load_serialized_info_trampoline<
            F: Fn(&Discoverer, &str) -> Option<DiscovererInfo> + Send + Sync + 'static,
        >(
            this: *mut ffi::GstDiscoverer,
            uri: *mut std::ffi::c_char,
            f: glib::ffi::gpointer,
        ) -> *mut ffi::GstDiscovererInfo {
            let f: &F = &*(f as *const F);
            f(
                &from_glib_borrow(this),
                &glib::GString::from_glib_borrow(uri),
            )
            .to_glib_full()
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"load-serialized-info".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    load_serialized_info_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// This signal is emitted after the source element has been created for, so
    /// the URI being discovered, so it can be configured by setting additional
    /// properties (e.g. set a proxy server for an http source, or set the device
    /// and read speed for an audio cd source).
    ///
    /// This signal is usually emitted from the context of a GStreamer streaming
    /// thread.
    /// ## `source`
    /// source element
    #[doc(alias = "source-setup")]
    pub fn connect_source_setup<F: Fn(&Self, &gst::Element) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn source_setup_trampoline<
            F: Fn(&Discoverer, &gst::Element) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstDiscoverer,
            source: *mut gst::ffi::GstElement,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this), &from_glib_borrow(source))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"source-setup".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    source_setup_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Will be emitted when the discover starts analyzing the pending URIs
    #[doc(alias = "starting")]
    pub fn connect_starting<F: Fn(&Self) + Send + Sync + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn starting_trampoline<F: Fn(&Discoverer) + Send + Sync + 'static>(
            this: *mut ffi::GstDiscoverer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"starting".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    starting_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[cfg(feature = "v1_16")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_16")))]
    #[doc(alias = "use-cache")]
    pub fn connect_use_cache_notify<F: Fn(&Self) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn notify_use_cache_trampoline<
            F: Fn(&Discoverer) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstDiscoverer,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::use-cache".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_use_cache_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

unsafe impl Send for Discoverer {}
unsafe impl Sync for Discoverer {}