gstreamer/auto/

element.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
#![allow(deprecated)]

use crate::{
    ffi, Bus, Caps, Clock, ClockTime, Context, ElementFactory, Message, Object, Pad, PadTemplate,
    State, StateChange, StateChangeError, StateChangeReturn, StateChangeSuccess, URIType,
};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// GstElement is the abstract base class needed to construct an element that
    /// can be used in a GStreamer pipeline. Please refer to the plugin writers
    /// guide for more information on creating [`Element`][crate::Element] subclasses.
    ///
    /// The name of a [`Element`][crate::Element] can be get with `gst_element_get_name()` and set with
    /// `gst_element_set_name()`. For speed, GST_ELEMENT_NAME() can be used in the
    /// core when using the appropriate locking. Do not use this in plug-ins or
    /// applications in order to retain ABI compatibility.
    ///
    /// Elements can have pads (of the type [`Pad`][crate::Pad]). These pads link to pads on
    /// other elements. [`Buffer`][crate::Buffer] flow between these linked pads.
    /// A [`Element`][crate::Element] has a `GList` of [`Pad`][crate::Pad] structures for all their input (or sink)
    /// and output (or source) pads.
    /// Core and plug-in writers can add and remove pads with [`ElementExt::add_pad()`][crate::prelude::ElementExt::add_pad()]
    /// and [`ElementExt::remove_pad()`][crate::prelude::ElementExt::remove_pad()].
    ///
    /// An existing pad of an element can be retrieved by name with
    /// [`ElementExt::static_pad()`][crate::prelude::ElementExt::static_pad()]. A new dynamic pad can be created using
    /// [`ElementExt::request_pad()`][crate::prelude::ElementExt::request_pad()] with a [`PadTemplate`][crate::PadTemplate].
    /// An iterator of all pads can be retrieved with [`ElementExtManual::iterate_pads()`][crate::prelude::ElementExtManual::iterate_pads()].
    ///
    /// Elements can be linked through their pads.
    /// If the link is straightforward, use the [`ElementExtManual::link()`][crate::prelude::ElementExtManual::link()]
    /// convenience function to link two elements, or [`ElementExtManual::link_many()`][crate::prelude::ElementExtManual::link_many()]
    /// for more elements in a row.
    /// Use [`ElementExtManual::link_filtered()`][crate::prelude::ElementExtManual::link_filtered()] to link two elements constrained by
    /// a specified set of [`Caps`][crate::Caps].
    /// For finer control, use [`ElementExtManual::link_pads()`][crate::prelude::ElementExtManual::link_pads()] and
    /// [`ElementExtManual::link_pads_filtered()`][crate::prelude::ElementExtManual::link_pads_filtered()] to specify the pads to link on
    /// each element by name.
    ///
    /// Each element has a state (see [`State`][crate::State]). You can get and set the state
    /// of an element with [`ElementExt::state()`][crate::prelude::ElementExt::state()] and [`ElementExt::set_state()`][crate::prelude::ElementExt::set_state()].
    /// Setting a state triggers a [`StateChange`][crate::StateChange]. To get a string representation
    /// of a [`State`][crate::State], use `gst_element_state_get_name()`.
    ///
    /// You can get and set a [`Clock`][crate::Clock] on an element using [`ElementExt::clock()`][crate::prelude::ElementExt::clock()]
    /// and [`ElementExt::set_clock()`][crate::prelude::ElementExt::set_clock()].
    /// Some elements can provide a clock for the pipeline if
    /// the [`ElementFlags::PROVIDE_CLOCK`][crate::ElementFlags::PROVIDE_CLOCK] flag is set. With the
    /// [`ElementExt::provide_clock()`][crate::prelude::ElementExt::provide_clock()] method one can retrieve the clock provided by
    /// such an element.
    /// Not all elements require a clock to operate correctly. If the
    /// [`ElementFlags::REQUIRE_CLOCK`][crate::ElementFlags::REQUIRE_CLOCK]() flag is set, a clock should be set on the
    /// element with [`ElementExt::set_clock()`][crate::prelude::ElementExt::set_clock()].
    ///
    /// Note that clock selection and distribution is normally handled by the
    /// toplevel [`Pipeline`][crate::Pipeline] so the clock functions are only to be used in very
    /// specific situations.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Signals
    ///
    ///
    /// #### `no-more-pads`
    ///  This signals that the element will not generate more dynamic pads.
    /// Note that this signal will usually be emitted from the context of
    /// the streaming thread.
    ///
    ///
    ///
    ///
    /// #### `pad-added`
    ///  a new [`Pad`][crate::Pad] has been added to the element. Note that this signal will
    /// usually be emitted from the context of the streaming thread. Also keep in
    /// mind that if you add new elements to the pipeline in the signal handler
    /// you will need to set them to the desired target state with
    /// [`ElementExt::set_state()`][crate::prelude::ElementExt::set_state()] or [`ElementExt::sync_state_with_parent()`][crate::prelude::ElementExt::sync_state_with_parent()].
    ///
    ///
    ///
    ///
    /// #### `pad-removed`
    ///  a [`Pad`][crate::Pad] has been removed from the element
    ///
    ///
    /// <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
    ///
    /// [`ElementExt`][trait@crate::prelude::ElementExt], [`GstObjectExt`][trait@crate::prelude::GstObjectExt], [`trait@glib::ObjectExt`], [`ElementExtManual`][trait@crate::prelude::ElementExtManual]
    #[doc(alias = "GstElement")]
    pub struct Element(Object<ffi::GstElement, ffi::GstElementClass>) @extends Object;

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

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

    /// Creates an element for handling the given URI.
    /// ## `type_`
    /// Whether to create a source or a sink
    /// ## `uri`
    /// URI to create an element for
    /// ## `elementname`
    /// Name of created element, can be [`None`].
    ///
    /// # Returns
    ///
    /// a new element or [`None`] if none
    /// could be created
    #[doc(alias = "gst_element_make_from_uri")]
    pub fn make_from_uri(
        type_: URIType,
        uri: &str,
        elementname: Option<&str>,
    ) -> Result<Element, glib::Error> {
        assert_initialized_main_thread!();
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gst_element_make_from_uri(
                type_.into_glib(),
                uri.to_glib_none().0,
                elementname.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_none(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}

unsafe impl Send for Element {}
unsafe impl Sync for Element {}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::Element>> Sealed for T {}
}

/// Trait containing all [`struct@Element`] methods.
///
/// # Implementors
///
/// [`Bin`][struct@crate::Bin], [`Element`][struct@crate::Element], [`TagSetter`][struct@crate::TagSetter], [`TocSetter`][struct@crate::TocSetter]
pub trait ElementExt: IsA<Element> + sealed::Sealed + 'static {
    /// Abort the state change of the element. This function is used
    /// by elements that do asynchronous state changes and find out
    /// something is wrong.
    ///
    /// This function should be called with the STATE_LOCK held.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_abort_state")]
    fn abort_state(&self) {
        unsafe {
            ffi::gst_element_abort_state(self.as_ref().to_glib_none().0);
        }
    }

    /// Adds a pad (link point) to `self`. `pad`'s parent will be set to `self`;
    /// see [`GstObjectExt::set_parent()`][crate::prelude::GstObjectExt::set_parent()] for refcounting information.
    ///
    /// Pads are automatically activated when added in the PAUSED or PLAYING
    /// state.
    ///
    /// The pad and the element should be unlocked when calling this function.
    ///
    /// This function will emit the [`pad-added`][struct@crate::Element#pad-added] signal on the element.
    /// ## `pad`
    /// the [`Pad`][crate::Pad] to add to the element.
    ///
    /// # Returns
    ///
    /// [`true`] if the pad could be added. This function can fail when
    /// a pad with the same name already existed or the pad already had another
    /// parent.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_add_pad")]
    fn add_pad(&self, pad: &impl IsA<Pad>) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_element_add_pad(
                    self.as_ref().to_glib_none().0,
                    pad.as_ref().to_glib_none().0
                ),
                "Failed to add pad"
            )
        }
    }

    /// Perform `transition` on `self`.
    ///
    /// This function must be called with STATE_LOCK held and is mainly used
    /// internally.
    /// ## `transition`
    /// the requested transition
    ///
    /// # Returns
    ///
    /// the [`StateChangeReturn`][crate::StateChangeReturn] of the state transition.
    #[doc(alias = "gst_element_change_state")]
    fn change_state(
        &self,
        transition: StateChange,
    ) -> Result<StateChangeSuccess, StateChangeError> {
        unsafe {
            try_from_glib(ffi::gst_element_change_state(
                self.as_ref().to_glib_none().0,
                transition.into_glib(),
            ))
        }
    }

    /// Commit the state change of the element and proceed to the next
    /// pending state if any. This function is used
    /// by elements that do asynchronous state changes.
    /// The core will normally call this method automatically when an
    /// element returned [`StateChangeReturn::Success`][crate::StateChangeReturn::Success] from the state change function.
    ///
    /// If after calling this method the element still has not reached
    /// the pending state, the next state change is performed.
    ///
    /// This method is used internally and should normally not be called by plugins
    /// or applications.
    ///
    /// This function must be called with STATE_LOCK held.
    /// ## `ret`
    /// The previous state return value
    ///
    /// # Returns
    ///
    /// The result of the commit state change.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_continue_state")]
    fn continue_state(
        &self,
        ret: impl Into<StateChangeReturn>,
    ) -> Result<StateChangeSuccess, StateChangeError> {
        unsafe {
            try_from_glib(ffi::gst_element_continue_state(
                self.as_ref().to_glib_none().0,
                ret.into().into_glib(),
            ))
        }
    }

    /// Creates a pad for each pad template that is always available.
    /// This function is only useful during object initialization of
    /// subclasses of [`Element`][crate::Element].
    #[doc(alias = "gst_element_create_all_pads")]
    fn create_all_pads(&self) {
        unsafe {
            ffi::gst_element_create_all_pads(self.as_ref().to_glib_none().0);
        }
    }

    /// Creates a stream-id for `self` by combining the upstream information with
    /// the `stream_id`.
    ///
    /// This function generates an unique stream-id by getting the upstream
    /// stream-start event stream ID and appending `stream_id` to it. If the element
    /// has no sinkpad it will generate an upstream stream-id by doing an URI query
    /// on the element and in the worst case just uses a random number. Source
    /// elements that don't implement the URI handler interface should ideally
    /// generate a unique, deterministic stream-id manually instead.
    ///
    /// Since stream IDs are sorted alphabetically, any numbers in the stream ID
    /// should be printed with a fixed number of characters, preceded by 0's, such as
    /// by using the format \`03u` instead of \`u`.
    /// ## `stream_id`
    /// The stream-id
    ///
    /// # Returns
    ///
    /// A stream-id for `self`.
    #[cfg(feature = "v1_24")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
    #[doc(alias = "gst_element_decorate_stream_id")]
    fn decorate_stream_id(&self, stream_id: &str) -> glib::GString {
        unsafe {
            from_glib_full(ffi::gst_element_decorate_stream_id(
                self.as_ref().to_glib_none().0,
                stream_id.to_glib_none().0,
            ))
        }
    }

    /// Call `func` with `user_data` for each of `self`'s pads. `func` will be called
    /// exactly once for each pad that exists at the time of this call, unless
    /// one of the calls to `func` returns [`false`] in which case we will stop
    /// iterating pads and return early. If new pads are added or pads are removed
    /// while pads are being iterated, this will not be taken into account until
    /// next time this function is used.
    /// ## `func`
    /// function to call for each pad
    ///
    /// # Returns
    ///
    /// [`false`] if `self` had no pads or if one of the calls to `func`
    ///  returned [`false`].
    #[doc(alias = "gst_element_foreach_pad")]
    fn foreach_pad<P: FnMut(&Element, &Pad) -> bool>(&self, func: P) -> bool {
        let mut func_data: P = func;
        unsafe extern "C" fn func_func<P: FnMut(&Element, &Pad) -> bool>(
            element: *mut ffi::GstElement,
            pad: *mut ffi::GstPad,
            user_data: glib::ffi::gpointer,
        ) -> glib::ffi::gboolean {
            let element = from_glib_borrow(element);
            let pad = from_glib_borrow(pad);
            let callback = user_data as *mut P;
            (*callback)(&element, &pad).into_glib()
        }
        let func = Some(func_func::<P> as _);
        let super_callback0: &mut P = &mut func_data;
        unsafe {
            from_glib(ffi::gst_element_foreach_pad(
                self.as_ref().to_glib_none().0,
                func,
                super_callback0 as *mut _ as *mut _,
            ))
        }
    }

    /// Call `func` with `user_data` for each of `self`'s sink pads. `func` will be
    /// called exactly once for each sink pad that exists at the time of this call,
    /// unless one of the calls to `func` returns [`false`] in which case we will stop
    /// iterating pads and return early. If new sink pads are added or sink pads
    /// are removed while the sink pads are being iterated, this will not be taken
    /// into account until next time this function is used.
    /// ## `func`
    /// function to call for each sink pad
    ///
    /// # Returns
    ///
    /// [`false`] if `self` had no sink pads or if one of the calls to `func`
    ///  returned [`false`].
    #[doc(alias = "gst_element_foreach_sink_pad")]
    fn foreach_sink_pad<P: FnMut(&Element, &Pad) -> bool>(&self, func: P) -> bool {
        let mut func_data: P = func;
        unsafe extern "C" fn func_func<P: FnMut(&Element, &Pad) -> bool>(
            element: *mut ffi::GstElement,
            pad: *mut ffi::GstPad,
            user_data: glib::ffi::gpointer,
        ) -> glib::ffi::gboolean {
            let element = from_glib_borrow(element);
            let pad = from_glib_borrow(pad);
            let callback = user_data as *mut P;
            (*callback)(&element, &pad).into_glib()
        }
        let func = Some(func_func::<P> as _);
        let super_callback0: &mut P = &mut func_data;
        unsafe {
            from_glib(ffi::gst_element_foreach_sink_pad(
                self.as_ref().to_glib_none().0,
                func,
                super_callback0 as *mut _ as *mut _,
            ))
        }
    }

    /// Call `func` with `user_data` for each of `self`'s source pads. `func` will be
    /// called exactly once for each source pad that exists at the time of this call,
    /// unless one of the calls to `func` returns [`false`] in which case we will stop
    /// iterating pads and return early. If new source pads are added or source pads
    /// are removed while the source pads are being iterated, this will not be taken
    /// into account until next time this function is used.
    /// ## `func`
    /// function to call for each source pad
    ///
    /// # Returns
    ///
    /// [`false`] if `self` had no source pads or if one of the calls
    ///  to `func` returned [`false`].
    #[doc(alias = "gst_element_foreach_src_pad")]
    fn foreach_src_pad<P: FnMut(&Element, &Pad) -> bool>(&self, func: P) -> bool {
        let mut func_data: P = func;
        unsafe extern "C" fn func_func<P: FnMut(&Element, &Pad) -> bool>(
            element: *mut ffi::GstElement,
            pad: *mut ffi::GstPad,
            user_data: glib::ffi::gpointer,
        ) -> glib::ffi::gboolean {
            let element = from_glib_borrow(element);
            let pad = from_glib_borrow(pad);
            let callback = user_data as *mut P;
            (*callback)(&element, &pad).into_glib()
        }
        let func = Some(func_func::<P> as _);
        let super_callback0: &mut P = &mut func_data;
        unsafe {
            from_glib(ffi::gst_element_foreach_src_pad(
                self.as_ref().to_glib_none().0,
                func,
                super_callback0 as *mut _ as *mut _,
            ))
        }
    }

    /// Returns the base time of the element. The base time is the
    /// absolute time of the clock when this element was last put to
    /// PLAYING. Subtracting the base time from the clock time gives
    /// the running time of the element.
    ///
    /// # Returns
    ///
    /// the base time of the element.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_get_base_time")]
    #[doc(alias = "get_base_time")]
    fn base_time(&self) -> Option<ClockTime> {
        unsafe {
            from_glib(ffi::gst_element_get_base_time(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Returns the bus of the element. Note that only a [`Pipeline`][crate::Pipeline] will provide a
    /// bus for the application.
    ///
    /// # Returns
    ///
    /// the element's [`Bus`][crate::Bus]. unref after
    /// usage.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_get_bus")]
    #[doc(alias = "get_bus")]
    fn bus(&self) -> Option<Bus> {
        unsafe { from_glib_full(ffi::gst_element_get_bus(self.as_ref().to_glib_none().0)) }
    }

    /// Gets the currently configured clock of the element. This is the clock as was
    /// last set with [`set_clock()`][Self::set_clock()].
    ///
    /// Elements in a pipeline will only have their clock set when the
    /// pipeline is in the PLAYING state.
    ///
    /// # Returns
    ///
    /// the [`Clock`][crate::Clock] of the element. unref after usage.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_get_clock")]
    #[doc(alias = "get_clock")]
    fn clock(&self) -> Option<Clock> {
        unsafe { from_glib_full(ffi::gst_element_get_clock(self.as_ref().to_glib_none().0)) }
    }

    /// Looks for an unlinked pad to which the given pad can link. It is not
    /// guaranteed that linking the pads will work, though it should work in most
    /// cases.
    ///
    /// This function will first attempt to find a compatible unlinked ALWAYS pad,
    /// and if none can be found, it will request a compatible REQUEST pad by looking
    /// at the templates of `self`.
    /// ## `pad`
    /// the [`Pad`][crate::Pad] to find a compatible one for.
    /// ## `caps`
    /// the [`Caps`][crate::Caps] to use as a filter.
    ///
    /// # Returns
    ///
    /// the [`Pad`][crate::Pad] to which a link
    ///  can be made, or [`None`] if one cannot be found. `gst_object_unref()`
    ///  after usage.
    #[doc(alias = "gst_element_get_compatible_pad")]
    #[doc(alias = "get_compatible_pad")]
    fn compatible_pad(&self, pad: &impl IsA<Pad>, caps: Option<&Caps>) -> Option<Pad> {
        unsafe {
            from_glib_full(ffi::gst_element_get_compatible_pad(
                self.as_ref().to_glib_none().0,
                pad.as_ref().to_glib_none().0,
                caps.to_glib_none().0,
            ))
        }
    }

    /// Retrieves a pad template from `self` that is compatible with `compattempl`.
    /// Pads from compatible templates can be linked together.
    /// ## `compattempl`
    /// the [`PadTemplate`][crate::PadTemplate] to find a compatible
    ///  template for
    ///
    /// # Returns
    ///
    /// a compatible [`PadTemplate`][crate::PadTemplate],
    ///  or [`None`] if none was found. No unreferencing is necessary.
    #[doc(alias = "gst_element_get_compatible_pad_template")]
    #[doc(alias = "get_compatible_pad_template")]
    fn compatible_pad_template(&self, compattempl: &PadTemplate) -> Option<PadTemplate> {
        unsafe {
            from_glib_none(ffi::gst_element_get_compatible_pad_template(
                self.as_ref().to_glib_none().0,
                compattempl.to_glib_none().0,
            ))
        }
    }

    /// Gets the context with `context_type` set on the element or NULL.
    ///
    /// MT safe.
    /// ## `context_type`
    /// a name of a context to retrieve
    ///
    /// # Returns
    ///
    /// A [`Context`][crate::Context] or NULL
    #[doc(alias = "gst_element_get_context")]
    #[doc(alias = "get_context")]
    fn context(&self, context_type: &str) -> Option<Context> {
        unsafe {
            from_glib_full(ffi::gst_element_get_context(
                self.as_ref().to_glib_none().0,
                context_type.to_glib_none().0,
            ))
        }
    }

    /// Gets the contexts set on the element.
    ///
    /// MT safe.
    ///
    /// # Returns
    ///
    /// List of [`Context`][crate::Context]
    #[doc(alias = "gst_element_get_contexts")]
    #[doc(alias = "get_contexts")]
    fn contexts(&self) -> Vec<Context> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::gst_element_get_contexts(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Retrieves the factory that was used to create this element.
    ///
    /// # Returns
    ///
    /// the [`ElementFactory`][crate::ElementFactory] used for creating this
    ///  element or [`None`] if element has not been registered (static element). no refcounting is needed.
    #[doc(alias = "gst_element_get_factory")]
    #[doc(alias = "get_factory")]
    fn factory(&self) -> Option<ElementFactory> {
        unsafe { from_glib_none(ffi::gst_element_get_factory(self.as_ref().to_glib_none().0)) }
    }

    /// Returns the start time of the element. The start time is the
    /// running time of the clock when this element was last put to PAUSED.
    ///
    /// Usually the start_time is managed by a toplevel element such as
    /// [`Pipeline`][crate::Pipeline].
    ///
    /// MT safe.
    ///
    /// # Returns
    ///
    /// the start time of the element.
    #[doc(alias = "gst_element_get_start_time")]
    #[doc(alias = "get_start_time")]
    fn start_time(&self) -> Option<ClockTime> {
        unsafe {
            from_glib(ffi::gst_element_get_start_time(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the state of the element.
    ///
    /// For elements that performed an ASYNC state change, as reported by
    /// [`set_state()`][Self::set_state()], this function will block up to the
    /// specified timeout value for the state change to complete.
    /// If the element completes the state change or goes into
    /// an error, this function returns immediately with a return value of
    /// [`StateChangeReturn::Success`][crate::StateChangeReturn::Success] or [`StateChangeReturn::Failure`][crate::StateChangeReturn::Failure] respectively.
    ///
    /// For elements that did not return [`StateChangeReturn::Async`][crate::StateChangeReturn::Async], this function
    /// returns the current and pending state immediately.
    ///
    /// This function returns [`StateChangeReturn::NoPreroll`][crate::StateChangeReturn::NoPreroll] if the element
    /// successfully changed its state but is not able to provide data yet.
    /// This mostly happens for live sources that only produce data in
    /// [`State::Playing`][crate::State::Playing]. While the state change return is equivalent to
    /// [`StateChangeReturn::Success`][crate::StateChangeReturn::Success], it is returned to the application to signal that
    /// some sink elements might not be able to complete their state change because
    /// an element is not producing data to complete the preroll. When setting the
    /// element to playing, the preroll will complete and playback will start.
    /// ## `timeout`
    /// a `GstClockTime` to specify the timeout for an async
    ///  state change or `GST_CLOCK_TIME_NONE` for infinite timeout.
    ///
    /// # Returns
    ///
    /// [`StateChangeReturn::Success`][crate::StateChangeReturn::Success] if the element has no more pending state
    ///  and the last state change succeeded, [`StateChangeReturn::Async`][crate::StateChangeReturn::Async] if the
    ///  element is still performing a state change or
    ///  [`StateChangeReturn::Failure`][crate::StateChangeReturn::Failure] if the last state change failed.
    ///
    /// MT safe.
    ///
    /// ## `state`
    /// a pointer to [`State`][crate::State] to hold the state.
    ///  Can be [`None`].
    ///
    /// ## `pending`
    /// a pointer to [`State`][crate::State] to hold the pending
    ///  state. Can be [`None`].
    #[doc(alias = "gst_element_get_state")]
    #[doc(alias = "get_state")]
    fn state(
        &self,
        timeout: impl Into<Option<ClockTime>>,
    ) -> (Result<StateChangeSuccess, StateChangeError>, State, State) {
        unsafe {
            let mut state = std::mem::MaybeUninit::uninit();
            let mut pending = std::mem::MaybeUninit::uninit();
            let ret = try_from_glib(ffi::gst_element_get_state(
                self.as_ref().to_glib_none().0,
                state.as_mut_ptr(),
                pending.as_mut_ptr(),
                timeout.into().into_glib(),
            ));
            (
                ret,
                from_glib(state.assume_init()),
                from_glib(pending.assume_init()),
            )
        }
    }

    /// Retrieves a pad from `self` by name. This version only retrieves
    /// already-existing (i.e. 'static') pads.
    /// ## `name`
    /// the name of the static [`Pad`][crate::Pad] to retrieve.
    ///
    /// # Returns
    ///
    /// the requested [`Pad`][crate::Pad] if
    ///  found, otherwise [`None`]. unref after usage.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_get_static_pad")]
    #[doc(alias = "get_static_pad")]
    fn static_pad(&self, name: &str) -> Option<Pad> {
        unsafe {
            from_glib_full(ffi::gst_element_get_static_pad(
                self.as_ref().to_glib_none().0,
                name.to_glib_none().0,
            ))
        }
    }

    /// Checks if the state of an element is locked.
    /// If the state of an element is locked, state changes of the parent don't
    /// affect the element.
    /// This way you can leave currently unused elements inside bins. Just lock their
    /// state before changing the state from [`State::Null`][crate::State::Null].
    ///
    /// MT safe.
    ///
    /// # Returns
    ///
    /// [`true`], if the element's state is locked.
    #[doc(alias = "gst_element_is_locked_state")]
    fn is_locked_state(&self) -> bool {
        unsafe {
            from_glib(ffi::gst_element_is_locked_state(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Brings the element to the lost state. The current state of the
    /// element is copied to the pending state so that any call to
    /// [`state()`][Self::state()] will return [`StateChangeReturn::Async`][crate::StateChangeReturn::Async].
    ///
    /// An ASYNC_START message is posted. If the element was PLAYING, it will
    /// go to PAUSED. The element will be restored to its PLAYING state by
    /// the parent pipeline when it prerolls again.
    ///
    /// This is mostly used for elements that lost their preroll buffer
    /// in the [`State::Paused`][crate::State::Paused] or [`State::Playing`][crate::State::Playing] state after a flush,
    /// they will go to their pending state again when a new preroll buffer is
    /// queued. This function can only be called when the element is currently
    /// not in error or an async state change.
    ///
    /// This function is used internally and should normally not be called from
    /// plugins or applications.
    #[doc(alias = "gst_element_lost_state")]
    fn lost_state(&self) {
        unsafe {
            ffi::gst_element_lost_state(self.as_ref().to_glib_none().0);
        }
    }

    /// Use this function to signal that the element does not expect any more pads
    /// to show up in the current pipeline. This function should be called whenever
    /// pads have been added by the element itself. Elements with [`PadPresence::Sometimes`][crate::PadPresence::Sometimes]
    /// pad templates use this in combination with autopluggers to figure out that
    /// the element is done initializing its pads.
    ///
    /// This function emits the [`no-more-pads`][struct@crate::Element#no-more-pads] signal.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_no_more_pads")]
    fn no_more_pads(&self) {
        unsafe {
            ffi::gst_element_no_more_pads(self.as_ref().to_glib_none().0);
        }
    }

    /// Post a message on the element's [`Bus`][crate::Bus]. This function takes ownership of the
    /// message; if you want to access the message after this call, you should add an
    /// additional reference before calling.
    /// ## `message`
    /// a [`Message`][crate::Message] to post
    ///
    /// # Returns
    ///
    /// [`true`] if the message was successfully posted. The function returns
    /// [`false`] if the element did not have a bus.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_post_message")]
    fn post_message(&self, message: Message) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_element_post_message(
                    self.as_ref().to_glib_none().0,
                    message.into_glib_ptr()
                ),
                "Failed to post message"
            )
        }
    }

    /// Get the clock provided by the given element.
    /// > An element is only required to provide a clock in the PAUSED
    /// > state. Some elements can provide a clock in other states.
    ///
    /// # Returns
    ///
    /// the GstClock provided by the
    /// element or [`None`] if no clock could be provided. Unref after usage.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_provide_clock")]
    fn provide_clock(&self) -> Option<Clock> {
        unsafe {
            from_glib_full(ffi::gst_element_provide_clock(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Makes the element free the previously requested pad as obtained
    /// with [`request_pad()`][Self::request_pad()].
    ///
    /// This does not unref the pad. If the pad was created by using
    /// [`request_pad()`][Self::request_pad()], [`release_request_pad()`][Self::release_request_pad()] needs to be
    /// followed by `gst_object_unref()` to free the `pad`.
    ///
    /// MT safe.
    /// ## `pad`
    /// the [`Pad`][crate::Pad] to release.
    #[doc(alias = "gst_element_release_request_pad")]
    fn release_request_pad(&self, pad: &impl IsA<Pad>) {
        unsafe {
            ffi::gst_element_release_request_pad(
                self.as_ref().to_glib_none().0,
                pad.as_ref().to_glib_none().0,
            );
        }
    }

    /// Removes `pad` from `self`. `pad` will be destroyed if it has not been
    /// referenced elsewhere using [`GstObjectExt::unparent()`][crate::prelude::GstObjectExt::unparent()].
    ///
    /// This function is used by plugin developers and should not be used
    /// by applications. Pads that were dynamically requested from elements
    /// with [`request_pad()`][Self::request_pad()] should be released with the
    /// [`release_request_pad()`][Self::release_request_pad()] function instead.
    ///
    /// Pads are not automatically deactivated so elements should perform the needed
    /// steps to deactivate the pad in case this pad is removed in the PAUSED or
    /// PLAYING state. See [`PadExt::set_active()`][crate::prelude::PadExt::set_active()] for more information about
    /// deactivating pads.
    ///
    /// The pad and the element should be unlocked when calling this function.
    ///
    /// This function will emit the [`pad-removed`][struct@crate::Element#pad-removed] signal on the element.
    /// ## `pad`
    /// the [`Pad`][crate::Pad] to remove from the element.
    ///
    /// # Returns
    ///
    /// [`true`] if the pad could be removed. Can return [`false`] if the
    /// pad does not belong to the provided element.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_remove_pad")]
    fn remove_pad(&self, pad: &impl IsA<Pad>) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_element_remove_pad(
                    self.as_ref().to_glib_none().0,
                    pad.as_ref().to_glib_none().0
                ),
                "Failed to remove pad"
            )
        }
    }

    /// Retrieves a request pad from the element according to the provided template.
    /// Pad templates can be looked up using
    /// [`ElementFactory::static_pad_templates()`][crate::ElementFactory::static_pad_templates()].
    ///
    /// The pad should be released with [`release_request_pad()`][Self::release_request_pad()].
    /// ## `templ`
    /// a [`PadTemplate`][crate::PadTemplate] of which we want a pad of.
    /// ## `name`
    /// the name of the request [`Pad`][crate::Pad]
    /// to retrieve. Can be [`None`].
    /// ## `caps`
    /// the caps of the pad we want to
    /// request. Can be [`None`].
    ///
    /// # Returns
    ///
    /// requested [`Pad`][crate::Pad] if found,
    ///  otherwise [`None`]. Release after usage.
    #[doc(alias = "gst_element_request_pad")]
    fn request_pad(
        &self,
        templ: &PadTemplate,
        name: Option<&str>,
        caps: Option<&Caps>,
    ) -> Option<Pad> {
        unsafe {
            from_glib_full(ffi::gst_element_request_pad(
                self.as_ref().to_glib_none().0,
                templ.to_glib_none().0,
                name.to_glib_none().0,
                caps.to_glib_none().0,
            ))
        }
    }

    /// Set the base time of an element. See [`base_time()`][Self::base_time()].
    ///
    /// MT safe.
    /// ## `time`
    /// the base time to set.
    #[doc(alias = "gst_element_set_base_time")]
    fn set_base_time(&self, time: ClockTime) {
        unsafe {
            ffi::gst_element_set_base_time(self.as_ref().to_glib_none().0, time.into_glib());
        }
    }

    /// Sets the bus of the element. Increases the refcount on the bus.
    /// For internal use only, unless you're testing elements.
    ///
    /// MT safe.
    /// ## `bus`
    /// the [`Bus`][crate::Bus] to set.
    #[doc(alias = "gst_element_set_bus")]
    fn set_bus(&self, bus: Option<&Bus>) {
        unsafe {
            ffi::gst_element_set_bus(self.as_ref().to_glib_none().0, bus.to_glib_none().0);
        }
    }

    /// Sets the clock for the element. This function increases the
    /// refcount on the clock. Any previously set clock on the object
    /// is unreffed.
    /// ## `clock`
    /// the [`Clock`][crate::Clock] to set for the element.
    ///
    /// # Returns
    ///
    /// [`true`] if the element accepted the clock. An element can refuse a
    /// clock when it, for example, is not able to slave its internal clock to the
    /// `clock` or when it requires a specific clock to operate.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_set_clock")]
    fn set_clock(&self, clock: Option<&impl IsA<Clock>>) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_element_set_clock(
                    self.as_ref().to_glib_none().0,
                    clock.map(|p| p.as_ref()).to_glib_none().0
                ),
                "Failed to set clock"
            )
        }
    }

    /// Sets the context of the element. Increases the refcount of the context.
    ///
    /// MT safe.
    /// ## `context`
    /// the [`Context`][crate::Context] to set.
    #[doc(alias = "gst_element_set_context")]
    fn set_context(&self, context: &Context) {
        unsafe {
            ffi::gst_element_set_context(self.as_ref().to_glib_none().0, context.to_glib_none().0);
        }
    }

    /// Locks the state of an element, so state changes of the parent don't affect
    /// this element anymore.
    ///
    /// Note that this is racy if the state lock of the parent bin is not taken.
    /// The parent bin might've just checked the flag in another thread and as the
    /// next step proceed to change the child element's state.
    ///
    /// MT safe.
    /// ## `locked_state`
    /// [`true`] to lock the element's state
    ///
    /// # Returns
    ///
    /// [`true`] if the state was changed, [`false`] if bad parameters were given
    /// or the elements state-locking needed no change.
    #[doc(alias = "gst_element_set_locked_state")]
    fn set_locked_state(&self, locked_state: bool) -> bool {
        unsafe {
            from_glib(ffi::gst_element_set_locked_state(
                self.as_ref().to_glib_none().0,
                locked_state.into_glib(),
            ))
        }
    }

    /// Set the start time of an element. The start time of the element is the
    /// running time of the element when it last went to the PAUSED state. In READY
    /// or after a flushing seek, it is set to 0.
    ///
    /// Toplevel elements like [`Pipeline`][crate::Pipeline] will manage the start_time and
    /// base_time on its children. Setting the start_time to `GST_CLOCK_TIME_NONE`
    /// on such a toplevel element will disable the distribution of the base_time to
    /// the children and can be useful if the application manages the base_time
    /// itself, for example if you want to synchronize capture from multiple
    /// pipelines, and you can also ensure that the pipelines have the same clock.
    ///
    /// MT safe.
    /// ## `time`
    /// the base time to set.
    #[doc(alias = "gst_element_set_start_time")]
    fn set_start_time(&self, time: impl Into<Option<ClockTime>>) {
        unsafe {
            ffi::gst_element_set_start_time(
                self.as_ref().to_glib_none().0,
                time.into().into_glib(),
            );
        }
    }

    /// Sets the state of the element. This function will try to set the
    /// requested state by going through all the intermediary states and calling
    /// the class's state change function for each.
    ///
    /// This function can return [`StateChangeReturn::Async`][crate::StateChangeReturn::Async], in which case the
    /// element will perform the remainder of the state change asynchronously in
    /// another thread.
    /// An application can use [`state()`][Self::state()] to wait for the completion
    /// of the state change or it can wait for a `GST_MESSAGE_ASYNC_DONE` or
    /// `GST_MESSAGE_STATE_CHANGED` on the bus.
    ///
    /// State changes to [`State::Ready`][crate::State::Ready] or [`State::Null`][crate::State::Null] never return
    /// [`StateChangeReturn::Async`][crate::StateChangeReturn::Async].
    /// ## `state`
    /// the element's new [`State`][crate::State].
    ///
    /// # Returns
    ///
    /// Result of the state change using [`StateChangeReturn`][crate::StateChangeReturn].
    ///
    /// MT safe.
    #[doc(alias = "gst_element_set_state")]
    fn set_state(&self, state: State) -> Result<StateChangeSuccess, StateChangeError> {
        unsafe {
            try_from_glib(ffi::gst_element_set_state(
                self.as_ref().to_glib_none().0,
                state.into_glib(),
            ))
        }
    }

    /// Tries to change the state of the element to the same as its parent.
    /// If this function returns [`false`], the state of element is undefined.
    ///
    /// # Returns
    ///
    /// [`true`], if the element's state could be synced to the parent's state.
    ///
    /// MT safe.
    #[doc(alias = "gst_element_sync_state_with_parent")]
    fn sync_state_with_parent(&self) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_element_sync_state_with_parent(self.as_ref().to_glib_none().0),
                "Failed to sync state with parent"
            )
        }
    }

    /// Unlinks all source pads of the source element with all sink pads
    /// of the sink element to which they are linked.
    ///
    /// If the link has been made using [`ElementExtManual::link()`][crate::prelude::ElementExtManual::link()], it could have created an
    /// requestpad, which has to be released using [`release_request_pad()`][Self::release_request_pad()].
    /// ## `dest`
    /// the sink [`Element`][crate::Element] to unlink.
    #[doc(alias = "gst_element_unlink")]
    fn unlink(&self, dest: &impl IsA<Element>) {
        unsafe {
            ffi::gst_element_unlink(
                self.as_ref().to_glib_none().0,
                dest.as_ref().to_glib_none().0,
            );
        }
    }

    /// Unlinks the two named pads of the source and destination elements.
    ///
    /// This is a convenience function for [`PadExt::unlink()`][crate::prelude::PadExt::unlink()].
    /// ## `srcpadname`
    /// the name of the [`Pad`][crate::Pad] in source element.
    /// ## `dest`
    /// a [`Element`][crate::Element] containing the destination pad.
    /// ## `destpadname`
    /// the name of the [`Pad`][crate::Pad] in destination element.
    #[doc(alias = "gst_element_unlink_pads")]
    fn unlink_pads(&self, srcpadname: &str, dest: &impl IsA<Element>, destpadname: &str) {
        unsafe {
            ffi::gst_element_unlink_pads(
                self.as_ref().to_glib_none().0,
                srcpadname.to_glib_none().0,
                dest.as_ref().to_glib_none().0,
                destpadname.to_glib_none().0,
            );
        }
    }

    /// This signals that the element will not generate more dynamic pads.
    /// Note that this signal will usually be emitted from the context of
    /// the streaming thread.
    #[doc(alias = "no-more-pads")]
    fn connect_no_more_pads<F: Fn(&Self) + Send + Sync + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn no_more_pads_trampoline<
            P: IsA<Element>,
            F: Fn(&P) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstElement,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Element::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"no-more-pads\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    no_more_pads_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// a new [`Pad`][crate::Pad] has been added to the element. Note that this signal will
    /// usually be emitted from the context of the streaming thread. Also keep in
    /// mind that if you add new elements to the pipeline in the signal handler
    /// you will need to set them to the desired target state with
    /// [`set_state()`][Self::set_state()] or [`sync_state_with_parent()`][Self::sync_state_with_parent()].
    /// ## `new_pad`
    /// the pad that has been added
    #[doc(alias = "pad-added")]
    fn connect_pad_added<F: Fn(&Self, &Pad) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn pad_added_trampoline<
            P: IsA<Element>,
            F: Fn(&P, &Pad) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstElement,
            new_pad: *mut ffi::GstPad,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                Element::from_glib_borrow(this).unsafe_cast_ref(),
                &from_glib_borrow(new_pad),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"pad-added\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    pad_added_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// a [`Pad`][crate::Pad] has been removed from the element
    /// ## `old_pad`
    /// the pad that has been removed
    #[doc(alias = "pad-removed")]
    fn connect_pad_removed<F: Fn(&Self, &Pad) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn pad_removed_trampoline<
            P: IsA<Element>,
            F: Fn(&P, &Pad) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstElement,
            old_pad: *mut ffi::GstPad,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                Element::from_glib_borrow(this).unsafe_cast_ref(),
                &from_glib_borrow(old_pad),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"pad-removed\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    pad_removed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Element>> ElementExt for O {}