gstreamer/auto/

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

glib::wrapper! {
    /// [`Object`][crate::Object] provides a root for the object hierarchy tree filed in by the
    /// GStreamer library. It is currently a thin wrapper on top of
    /// `GInitiallyUnowned`. It is an abstract class that is not very usable on its own.
    ///
    /// [`Object`][crate::Object] gives us basic refcounting, parenting functionality and locking.
    /// Most of the functions are just extended for special GStreamer needs and can be
    /// found under the same name in the base class of [`Object`][crate::Object] which is [`glib::Object`][crate::glib::Object]
    /// (e.g. `g_object_ref()` becomes `gst_object_ref()`).
    ///
    /// Since [`Object`][crate::Object] derives from `GInitiallyUnowned`, it also inherits the
    /// floating reference. Be aware that functions such as [`GstBinExt::add()`][crate::prelude::GstBinExt::add()] and
    /// [`ElementExt::add_pad()`][crate::prelude::ElementExt::add_pad()] take ownership of the floating reference.
    ///
    /// In contrast to [`glib::Object`][crate::glib::Object] instances, [`Object`][crate::Object] adds a name property. The functions
    /// `gst_object_set_name()` and [`GstObjectExt::name()`][crate::prelude::GstObjectExt::name()] are used to set/get the name
    /// of the object.
    ///
    /// ## controlled properties
    ///
    /// Controlled properties offers a lightweight way to adjust gobject properties
    /// over stream-time. It works by using time-stamped value pairs that are queued
    /// for element-properties. At run-time the elements continuously pull value
    /// changes for the current stream-time.
    ///
    /// What needs to be changed in a [`Element`][crate::Element]?
    /// Very little - it is just two steps to make a plugin controllable!
    ///
    ///  * mark gobject-properties paramspecs that make sense to be controlled,
    ///  by GST_PARAM_CONTROLLABLE.
    ///
    ///  * when processing data (get, chain, loop function) at the beginning call
    ///  gst_object_sync_values(element,timestamp).
    ///  This will make the controller update all GObject properties that are
    ///  under its control with the current values based on the timestamp.
    ///
    /// What needs to be done in applications? Again it's not a lot to change.
    ///
    ///  * create a [`ControlSource`][crate::ControlSource].
    ///  csource = gst_interpolation_control_source_new ();
    ///  g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);
    ///
    ///  * Attach the [`ControlSource`][crate::ControlSource] on the controller to a property.
    ///  gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource));
    ///
    ///  * Set the control values
    ///  gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1);
    ///  gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2);
    ///
    ///  * start your pipeline
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `name`
    ///  Readable | Writeable | Construct
    ///
    ///
    /// #### `parent`
    ///  The parent of the object. Please note, that when changing the 'parent'
    /// property, we don't emit [`notify`][struct@crate::glib::Object#notify] and [`deep-notify`][struct@crate::Object#deep-notify]
    /// signals due to locking issues. In some cases one can use
    /// [`element-added`][struct@crate::Bin#element-added] or [`element-removed`][struct@crate::Bin#element-removed] signals on the parent to
    /// achieve a similar effect.
    ///
    /// Readable | Writeable
    ///
    /// ## Signals
    ///
    ///
    /// #### `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
    ///
    /// # Implements
    ///
    /// [`GstObjectExt`][trait@crate::prelude::GstObjectExt], [`trait@glib::ObjectExt`]
    #[doc(alias = "GstObject")]
    pub struct Object(Object<ffi::GstObject, ffi::GstObjectClass>);

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

impl Object {
    pub const NONE: Option<&'static Object> = None;

    /// Checks to see if there is any object named `name` in `list`. This function
    /// does not do any locking of any kind. You might want to protect the
    /// provided list with the lock of the owner of the list. This function
    /// will lock each [`Object`][crate::Object] in the list to compare the name, so be
    /// careful when passing a list with a locked object.
    /// ## `list`
    /// a list of [`Object`][crate::Object] to
    ///  check through
    /// ## `name`
    /// the name to search for
    ///
    /// # Returns
    ///
    /// [`true`] if a [`Object`][crate::Object] named `name` does not appear in `list`,
    /// [`false`] if it does.
    ///
    /// MT safe. Grabs and releases the LOCK of each object in the list.
    #[doc(alias = "gst_object_check_uniqueness")]
    pub fn check_uniqueness(list: &[Object], name: &str) -> bool {
        assert_initialized_main_thread!();
        unsafe {
            from_glib(ffi::gst_object_check_uniqueness(
                list.to_glib_none().0,
                name.to_glib_none().0,
            ))
        }
    }

    //#[doc(alias = "gst_object_default_deep_notify")]
    //pub fn default_deep_notify(object: &impl IsA<glib::Object>, orig: &impl IsA<Object>, pspec: /*Ignored*/&glib::ParamSpec, excluded_props: &[&str]) {
    //    unsafe { TODO: call ffi:gst_object_default_deep_notify() }
    //}

    //#[doc(alias = "gst_object_replace")]
    //pub fn replace(oldobj: Option<impl IsA<Object>>, newobj: Option<&impl IsA<Object>>) -> bool {
    //    unsafe { TODO: call ffi:gst_object_replace() }
    //}
}

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

unsafe impl Send for Object {}
unsafe impl Sync for Object {}

/// Trait containing all [`struct@Object`] methods.
///
/// # Implementors
///
/// [`Allocator`][struct@crate::Allocator], [`BufferPool`][struct@crate::BufferPool], [`Bus`][struct@crate::Bus], [`Clock`][struct@crate::Clock], [`ControlBinding`][struct@crate::ControlBinding], [`ControlSource`][struct@crate::ControlSource], [`DeviceMonitor`][struct@crate::DeviceMonitor], [`DeviceProvider`][struct@crate::DeviceProvider], [`Device`][struct@crate::Device], [`Element`][struct@crate::Element], [`Object`][struct@crate::Object], [`PadTemplate`][struct@crate::PadTemplate], [`Pad`][struct@crate::Pad], [`PluginFeature`][struct@crate::PluginFeature], [`Plugin`][struct@crate::Plugin], [`Registry`][struct@crate::Registry], [`StreamCollection`][struct@crate::StreamCollection], [`Stream`][struct@crate::Stream], [`TaskPool`][struct@crate::TaskPool], [`Task`][struct@crate::Task], [`Tracer`][struct@crate::Tracer]
pub trait GstObjectExt: IsA<Object> + 'static {
    /// Attach the [`ControlBinding`][crate::ControlBinding] to the object. If there already was a
    /// [`ControlBinding`][crate::ControlBinding] for this property it will be replaced.
    ///
    /// The object's reference count will be incremented, and any floating
    /// reference will be removed (see `gst_object_ref_sink()`)
    /// ## `binding`
    /// the [`ControlBinding`][crate::ControlBinding] that should be used
    ///
    /// # Returns
    ///
    /// [`false`] if the given `binding` has not been setup for this object or
    /// has been setup for a non suitable property, [`true`] otherwise.
    #[doc(alias = "gst_object_add_control_binding")]
    fn add_control_binding(
        &self,
        binding: &impl IsA<ControlBinding>,
    ) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_object_add_control_binding(
                    self.as_ref().to_glib_none().0,
                    binding.as_ref().to_glib_none().0
                ),
                "Failed to add control binding"
            )
        }
    }

    /// A default error function that uses `g_printerr()` to display the error message
    /// and the optional debug string..
    ///
    /// The default handler will simply print the error string using g_print.
    /// ## `error`
    /// the GError.
    /// ## `debug`
    /// an additional debug information string, or [`None`]
    #[doc(alias = "gst_object_default_error")]
    fn default_error(&self, error: &glib::Error, debug: Option<&str>) {
        unsafe {
            ffi::gst_object_default_error(
                self.as_ref().to_glib_none().0,
                error.to_glib_none().0,
                debug.to_glib_none().0,
            );
        }
    }

    /// Gets the corresponding [`ControlBinding`][crate::ControlBinding] for the property. This should be
    /// unreferenced again after use.
    /// ## `property_name`
    /// name of the property
    ///
    /// # Returns
    ///
    /// the [`ControlBinding`][crate::ControlBinding] for
    /// `property_name` or [`None`] if the property is not controlled.
    #[doc(alias = "gst_object_get_control_binding")]
    #[doc(alias = "get_control_binding")]
    fn control_binding(&self, property_name: &str) -> Option<ControlBinding> {
        unsafe {
            from_glib_full(ffi::gst_object_get_control_binding(
                self.as_ref().to_glib_none().0,
                property_name.to_glib_none().0,
            ))
        }
    }

    /// Obtain the control-rate for this `self`. Audio processing [`Element`][crate::Element]
    /// objects will use this rate to sub-divide their processing loop and call
    /// [`sync_values()`][Self::sync_values()] in between. The length of the processing segment
    /// should be up to `control`-rate nanoseconds.
    ///
    /// If the `self` is not under property control, this will return
    /// `GST_CLOCK_TIME_NONE`. This allows the element to avoid the sub-dividing.
    ///
    /// The control-rate is not expected to change if the element is in
    /// [`State::Paused`][crate::State::Paused] or [`State::Playing`][crate::State::Playing].
    ///
    /// # Returns
    ///
    /// the control rate in nanoseconds
    #[doc(alias = "gst_object_get_control_rate")]
    #[doc(alias = "get_control_rate")]
    fn control_rate(&self) -> Option<ClockTime> {
        unsafe {
            from_glib(ffi::gst_object_get_control_rate(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Returns a copy of the name of `self`.
    /// Caller should `g_free()` the return value after usage.
    /// For a nameless object, this returns [`None`], which you can safely `g_free()`
    /// as well.
    ///
    /// Free-function: g_free
    ///
    /// # Returns
    ///
    /// the name of `self`. `g_free()`
    /// after usage.
    ///
    /// MT safe. This function grabs and releases `self`'s LOCK.
    #[doc(alias = "gst_object_get_name")]
    #[doc(alias = "get_name")]
    fn name(&self) -> glib::GString {
        unsafe { from_glib_full(ffi::gst_object_get_name(self.as_ref().to_glib_none().0)) }
    }

    /// Returns the parent of `self`. This function increases the refcount
    /// of the parent object so you should `gst_object_unref()` it after usage.
    ///
    /// # Returns
    ///
    /// parent of `self`, this can be
    ///  [`None`] if `self` has no parent. unref after usage.
    ///
    /// MT safe. Grabs and releases `self`'s LOCK.
    #[doc(alias = "gst_object_get_parent")]
    #[doc(alias = "get_parent")]
    #[must_use]
    fn parent(&self) -> Option<Object> {
        unsafe { from_glib_full(ffi::gst_object_get_parent(self.as_ref().to_glib_none().0)) }
    }

    /// Generates a string describing the path of `self` in
    /// the object hierarchy. Only useful (or used) for debugging.
    ///
    /// Free-function: g_free
    ///
    /// # Returns
    ///
    /// a string describing the path of `self`. You must
    ///  `g_free()` the string after usage.
    ///
    /// MT safe. Grabs and releases the [`Object`][crate::Object]'s LOCK for all objects
    ///  in the hierarchy.
    #[doc(alias = "gst_object_get_path_string")]
    #[doc(alias = "get_path_string")]
    fn path_string(&self) -> glib::GString {
        unsafe {
            from_glib_full(ffi::gst_object_get_path_string(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Returns the toplevel parent of `self`. This function increases the refcount
    /// of the toplevel object so you should `gst_object_unref()` it after usage.
    ///
    /// # Returns
    ///
    /// toplevel of `self`, or `self` itself if it has no
    ///  parent. unref after usage.
    ///
    /// MT safe. Grabs and releases `self`'s LOCK.
    #[cfg(feature = "v1_28")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_28")))]
    #[doc(alias = "gst_object_get_toplevel")]
    #[doc(alias = "get_toplevel")]
    #[must_use]
    fn toplevel(&self) -> Object {
        unsafe { from_glib_full(ffi::gst_object_get_toplevel(self.as_ref().to_glib_none().0)) }
    }

    /// Gets the value for the given controlled property at the requested time.
    /// ## `property_name`
    /// the name of the property to get
    /// ## `timestamp`
    /// the time the control-change should be read from
    ///
    /// # Returns
    ///
    /// the GValue of the property at the given time,
    /// or [`None`] if the property isn't controlled.
    #[doc(alias = "gst_object_get_value")]
    #[doc(alias = "get_value")]
    fn value(
        &self,
        property_name: &str,
        timestamp: impl Into<Option<ClockTime>>,
    ) -> Option<glib::Value> {
        unsafe {
            from_glib_full(ffi::gst_object_get_value(
                self.as_ref().to_glib_none().0,
                property_name.to_glib_none().0,
                timestamp.into().into_glib(),
            ))
        }
    }

    //#[doc(alias = "gst_object_get_value_array")]
    //#[doc(alias = "get_value_array")]
    //fn is_value_array(&self, property_name: &str, timestamp: impl Into<Option<ClockTime>>, interval: impl Into<Option<ClockTime>>, values: /*Unimplemented*/&[&Basic: Pointer]) -> bool {
    //    unsafe { TODO: call ffi:gst_object_get_value_array() }
    //}

    /// Check if the `self` has active controlled properties.
    ///
    /// # Returns
    ///
    /// [`true`] if the object has active controlled properties
    #[doc(alias = "gst_object_has_active_control_bindings")]
    fn has_active_control_bindings(&self) -> bool {
        unsafe {
            from_glib(ffi::gst_object_has_active_control_bindings(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Check if `self` has an ancestor `ancestor` somewhere up in
    /// the hierarchy. One can e.g. check if a [`Element`][crate::Element] is inside a [`Pipeline`][crate::Pipeline].
    ///
    /// # Deprecated
    ///
    /// Use [`has_as_ancestor()`][Self::has_as_ancestor()] instead.
    ///
    /// MT safe. Grabs and releases `self`'s locks.
    /// ## `ancestor`
    /// a [`Object`][crate::Object] to check as ancestor
    ///
    /// # Returns
    ///
    /// [`true`] if `ancestor` is an ancestor of `self`.
    #[doc(alias = "gst_object_has_ancestor")]
    fn has_ancestor(&self, ancestor: &impl IsA<Object>) -> bool {
        unsafe {
            from_glib(ffi::gst_object_has_ancestor(
                self.as_ref().to_glib_none().0,
                ancestor.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Check if `self` has an ancestor `ancestor` somewhere up in
    /// the hierarchy. One can e.g. check if a [`Element`][crate::Element] is inside a [`Pipeline`][crate::Pipeline].
    /// ## `ancestor`
    /// a [`Object`][crate::Object] to check as ancestor
    ///
    /// # Returns
    ///
    /// [`true`] if `ancestor` is an ancestor of `self`.
    ///
    /// MT safe. Grabs and releases `self`'s locks.
    #[doc(alias = "gst_object_has_as_ancestor")]
    fn has_as_ancestor(&self, ancestor: &impl IsA<Object>) -> bool {
        unsafe {
            from_glib(ffi::gst_object_has_as_ancestor(
                self.as_ref().to_glib_none().0,
                ancestor.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Check if `parent` is the parent of `self`.
    /// E.g. a [`Element`][crate::Element] can check if it owns a given [`Pad`][crate::Pad].
    /// ## `parent`
    /// a [`Object`][crate::Object] to check as parent
    ///
    /// # Returns
    ///
    /// [`false`] if either `self` or `parent` is [`None`]. [`true`] if `parent` is
    ///  the parent of `self`. Otherwise [`false`].
    ///
    /// MT safe. Grabs and releases `self`'s locks.
    #[doc(alias = "gst_object_has_as_parent")]
    fn has_as_parent(&self, parent: &impl IsA<Object>) -> bool {
        unsafe {
            from_glib(ffi::gst_object_has_as_parent(
                self.as_ref().to_glib_none().0,
                parent.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Removes the corresponding [`ControlBinding`][crate::ControlBinding]. If it was the
    /// last ref of the binding, it will be disposed.
    /// ## `binding`
    /// the binding
    ///
    /// # Returns
    ///
    /// [`true`] if the binding could be removed.
    #[doc(alias = "gst_object_remove_control_binding")]
    fn remove_control_binding(&self, binding: &impl IsA<ControlBinding>) -> bool {
        unsafe {
            from_glib(ffi::gst_object_remove_control_binding(
                self.as_ref().to_glib_none().0,
                binding.as_ref().to_glib_none().0,
            ))
        }
    }

    /// This function is used to disable the control bindings on a property for
    /// some time, i.e. [`sync_values()`][Self::sync_values()] will do nothing for the
    /// property.
    /// ## `property_name`
    /// property to disable
    /// ## `disabled`
    /// boolean that specifies whether to disable the controller
    /// or not.
    #[doc(alias = "gst_object_set_control_binding_disabled")]
    fn set_control_binding_disabled(&self, property_name: &str, disabled: bool) {
        unsafe {
            ffi::gst_object_set_control_binding_disabled(
                self.as_ref().to_glib_none().0,
                property_name.to_glib_none().0,
                disabled.into_glib(),
            );
        }
    }

    /// This function is used to disable all controlled properties of the `self` for
    /// some time, i.e. [`sync_values()`][Self::sync_values()] will do nothing.
    /// ## `disabled`
    /// boolean that specifies whether to disable the controller
    /// or not.
    #[doc(alias = "gst_object_set_control_bindings_disabled")]
    fn set_control_bindings_disabled(&self, disabled: bool) {
        unsafe {
            ffi::gst_object_set_control_bindings_disabled(
                self.as_ref().to_glib_none().0,
                disabled.into_glib(),
            );
        }
    }

    /// Change the control-rate for this `self`. Audio processing [`Element`][crate::Element]
    /// objects will use this rate to sub-divide their processing loop and call
    /// [`sync_values()`][Self::sync_values()] in between. The length of the processing segment
    /// should be up to `control`-rate nanoseconds.
    ///
    /// The control-rate should not change if the element is in [`State::Paused`][crate::State::Paused] or
    /// [`State::Playing`][crate::State::Playing].
    /// ## `control_rate`
    /// the new control-rate in nanoseconds.
    #[doc(alias = "gst_object_set_control_rate")]
    fn set_control_rate(&self, control_rate: impl Into<Option<ClockTime>>) {
        unsafe {
            ffi::gst_object_set_control_rate(
                self.as_ref().to_glib_none().0,
                control_rate.into().into_glib(),
            );
        }
    }

    /// Returns a suggestion for timestamps where buffers should be split
    /// to get best controller results.
    ///
    /// # Returns
    ///
    /// Returns the suggested timestamp or `GST_CLOCK_TIME_NONE`
    /// if no control-rate was set.
    #[doc(alias = "gst_object_suggest_next_sync")]
    fn suggest_next_sync(&self) -> Option<ClockTime> {
        unsafe {
            from_glib(ffi::gst_object_suggest_next_sync(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Sets the properties of the object, according to the `GstControlSources` that
    /// (maybe) handle them and for the given timestamp.
    ///
    /// If this function fails, it is most likely the application developers fault.
    /// Most probably the control sources are not setup correctly.
    /// ## `timestamp`
    /// the time that should be processed
    ///
    /// # Returns
    ///
    /// [`true`] if the controller values could be applied to the object
    /// properties, [`false`] otherwise
    #[doc(alias = "gst_object_sync_values")]
    fn sync_values(&self, timestamp: ClockTime) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_object_sync_values(self.as_ref().to_glib_none().0, timestamp.into_glib()),
                "Failed to sync values"
            )
        }
    }

    /// Clear the parent of `self`, removing the associated reference.
    /// This function decreases the refcount of `self`.
    ///
    /// MT safe. Grabs and releases `self`'s lock.
    #[doc(alias = "gst_object_unparent")]
    fn unparent(&self) {
        unsafe {
            ffi::gst_object_unparent(self.as_ref().to_glib_none().0);
        }
    }

    //#[doc(alias = "deep-notify")]
    //fn connect_deep_notify<Unsupported or ignored types>(&self, detail: Option<&str>, f: F) -> SignalHandlerId {
    //    Ignored prop: GObject.ParamSpec
    //}

    #[doc(alias = "parent")]
    fn connect_parent_notify<F: Fn(&Self) + Send + Sync + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_parent_trampoline<
            P: IsA<Object>,
            F: Fn(&P) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstObject,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(Object::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::parent".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_parent_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Object>> GstObjectExt for O {}