Trait gstreamer::prelude::ElementExtManual

pub trait ElementExtManual: Sealed + IsA<Element> + 'static {
    // Provided methods
    fn element_class(&self) -> &Class<Element> { ... }
    fn current_state(&self) -> State { ... }
    fn pending_state(&self) -> State { ... }
    fn query(&self, query: &mut QueryRef) -> bool { ... }
    fn send_event(&self, event: impl Into<Event>) -> bool { ... }
    fn metadata<'a>(&self, key: &str) -> Option<&'a str> { ... }
    fn pad_template(&self, name: &str) -> Option<PadTemplate> { ... }
    fn pad_template_list(&self) -> List<PadTemplate> { ... }
    fn message_full<T: MessageErrorDomain>(
        &self,
        type_: ElementMessageType,
        code: T,
        message: Option<&str>,
        debug: Option<&str>,
        file: &str,
        function: &str,
        line: u32,
    ) { ... }
    fn set_element_flags(&self, flags: ElementFlags) { ... }
    fn unset_element_flags(&self, flags: ElementFlags) { ... }
    fn element_flags(&self) -> ElementFlags { ... }
    fn message_full_with_details<T: MessageErrorDomain>(
        &self,
        type_: ElementMessageType,
        code: T,
        message: Option<&str>,
        debug: Option<&str>,
        file: &str,
        function: &str,
        line: u32,
        structure: Structure,
    ) { ... }
    fn post_error_message(&self, msg: ErrorMessage) { ... }
    fn iterate_pads(&self) -> Iterator<Pad> { ... }
    fn iterate_sink_pads(&self) -> Iterator<Pad> { ... }
    fn iterate_src_pads(&self) -> Iterator<Pad> { ... }
    fn pads(&self) -> Vec<Pad> { ... }
    fn sink_pads(&self) -> Vec<Pad> { ... }
    fn src_pads(&self) -> Vec<Pad> { ... }
    fn num_pads(&self) -> u16 { ... }
    fn num_sink_pads(&self) -> u16 { ... }
    fn num_src_pads(&self) -> u16 { ... }
    fn add_property_deep_notify_watch(
        &self,
        property_name: Option<&str>,
        include_value: bool,
    ) -> NotifyWatchId { ... }
    fn add_property_notify_watch(
        &self,
        property_name: Option<&str>,
        include_value: bool,
    ) -> NotifyWatchId { ... }
    fn remove_property_notify_watch(&self, watch_id: NotifyWatchId) { ... }
    fn query_convert<U: SpecificFormattedValueFullRange>(
        &self,
        src_val: impl FormattedValue,
    ) -> Option<U> { ... }
    fn query_convert_generic(
        &self,
        src_val: impl FormattedValue,
        dest_format: Format,
    ) -> Option<GenericFormattedValue> { ... }
    fn query_duration<T: SpecificFormattedValueIntrinsic>(&self) -> Option<T> { ... }
    fn query_duration_generic(
        &self,
        format: Format,
    ) -> Option<GenericFormattedValue> { ... }
    fn query_position<T: SpecificFormattedValueIntrinsic>(&self) -> Option<T> { ... }
    fn query_position_generic(
        &self,
        format: Format,
    ) -> Option<GenericFormattedValue> { ... }
    fn seek<V: FormattedValue>(
        &self,
        rate: f64,
        flags: SeekFlags,
        start_type: SeekType,
        start: V,
        stop_type: SeekType,
        stop: impl CompatibleFormattedValue<V>,
    ) -> Result<(), BoolError> { ... }
    fn seek_simple(
        &self,
        seek_flags: SeekFlags,
        seek_pos: impl FormattedValue,
    ) -> Result<(), BoolError> { ... }
    fn call_async<F>(&self, func: F)
       where F: FnOnce(&Self) + Send + 'static { ... }
    fn call_async_future<F, T>(
        &self,
        func: F,
    ) -> Pin<Box<dyn Future<Output = T> + Send + 'static>>
       where F: FnOnce(&Self) -> T + Send + 'static,
             T: Send + 'static { ... }
    fn current_running_time(&self) -> Option<ClockTime> { ... }
    fn current_clock_time(&self) -> Option<ClockTime> { ... }
    fn request_pad_simple(&self, name: &str) -> Option<Pad> { ... }
    fn link(&self, dest: &impl IsA<Element>) -> Result<(), BoolError> { ... }
    fn link_filtered(
        &self,
        dest: &impl IsA<Element>,
        filter: &Caps,
    ) -> Result<(), BoolError> { ... }
    fn link_pads(
        &self,
        srcpadname: Option<&str>,
        dest: &impl IsA<Element>,
        destpadname: Option<&str>,
    ) -> Result<(), BoolError> { ... }
    fn link_pads_filtered(
        &self,
        srcpadname: Option<&str>,
        dest: &impl IsA<Element>,
        destpadname: Option<&str>,
        filter: &Caps,
    ) -> Result<(), BoolError> { ... }
    fn link_pads_full(
        &self,
        srcpadname: Option<&str>,
        dest: &impl IsA<Element>,
        destpadname: Option<&str>,
        flags: PadLinkCheck,
    ) -> Result<(), BoolError> { ... }
}

Provided Methods

fn element_class(&self) -> &Class<Element>

fn current_state(&self) -> State

fn pending_state(&self) -> State

fn query(&self, query: &mut QueryRef) -> bool

Performs a query on the given element.

For elements that don’t implement a query handler, this function forwards the query to a random srcpad or to the peer of a random linked sinkpad of this element.

Please note that some queries might need a running pipeline to work.

query

the Query.

Returns

true if the query could be performed.

MT safe.

fn send_event(&self, event: impl Into<Event>) -> bool

Sends an event to an element. If the element doesn’t implement an event handler, the event will be pushed on a random linked sink pad for downstream events or a random linked source pad for upstream events.

This function takes ownership of the provided event so you should gst_event_ref() it if you want to reuse the event after this call.

MT safe.

event

the Event to send to the element.

Returns

true if the event was handled. Events that trigger a preroll (such as flushing seeks and steps) will emit GST_MESSAGE_ASYNC_DONE.

fn metadata<'a>(&self, key: &str) -> Option<&'a str>

Get metadata with key in klass.

key

the key to get

Returns

the metadata for key.

fn pad_template(&self, name: &str) -> Option<PadTemplate>

Retrieves a padtemplate from self with the given name.

name

the name of the PadTemplate to get.

Returns

the PadTemplate with the given name, or None if none was found. No unreferencing is necessary.

fn pad_template_list(&self) -> List<PadTemplate>

Retrieves a list of the pad templates associated with self. The list must not be modified by the calling code.

Returns

the GList of pad templates.

fn message_full<T: MessageErrorDomain>( &self, type_: ElementMessageType, code: T, message: Option<&str>, debug: Option<&str>, file: &str, function: &str, line: u32, )

Post an error, warning or info message on the bus from inside an element.

type_ must be of GST_MESSAGE_ERROR, GST_MESSAGE_WARNING or GST_MESSAGE_INFO.

MT safe.

type_

the GstMessageType

domain

the GStreamer GError domain this message belongs to

code

the GError code belonging to the domain

text

an allocated text string to be used as a replacement for the default message connected to code, or None

debug

an allocated debug message to be used as a replacement for the default debugging information, or None

file

the source code file where the error was generated

function

the source code function where the error was generated

line

the source code line where the error was generated

fn set_element_flags(&self, flags: ElementFlags)

fn unset_element_flags(&self, flags: ElementFlags)

fn element_flags(&self) -> ElementFlags

fn message_full_with_details<T: MessageErrorDomain>( &self, type_: ElementMessageType, code: T, message: Option<&str>, debug: Option<&str>, file: &str, function: &str, line: u32, structure: Structure, )

Post an error, warning or info message on the bus from inside an element.

type_ must be of GST_MESSAGE_ERROR, GST_MESSAGE_WARNING or GST_MESSAGE_INFO.

type_

the GstMessageType

domain

the GStreamer GError domain this message belongs to

code

the GError code belonging to the domain

text

an allocated text string to be used as a replacement for the default message connected to code, or None

debug

an allocated debug message to be used as a replacement for the default debugging information, or None

file

the source code file where the error was generated

function

the source code function where the error was generated

line

the source code line where the error was generated

structure

optional details structure

fn post_error_message(&self, msg: ErrorMessage)

fn iterate_pads(&self) -> Iterator<Pad>

Retrieves an iterator of self’s pads. The iterator should be freed after usage. Also more specialized iterators exists such as iterate_src_pads() or iterate_sink_pads().

The order of pads returned by the iterator will be the order in which the pads were added to the element.

Returns

the GstIterator of Pad.

MT safe.

fn iterate_sink_pads(&self) -> Iterator<Pad>

Retrieves an iterator of self’s sink pads.

The order of pads returned by the iterator will be the order in which the pads were added to the element.

Returns

the GstIterator of Pad.

MT safe.

fn iterate_src_pads(&self) -> Iterator<Pad>

Retrieves an iterator of self’s source pads.

The order of pads returned by the iterator will be the order in which the pads were added to the element.

Returns

the GstIterator of Pad.

MT safe.

fn pads(&self) -> Vec<Pad>

fn sink_pads(&self) -> Vec<Pad>

fn src_pads(&self) -> Vec<Pad>

fn num_pads(&self) -> u16

fn num_sink_pads(&self) -> u16

fn num_src_pads(&self) -> u16

fn add_property_deep_notify_watch( &self, property_name: Option<&str>, include_value: bool, ) -> NotifyWatchId

property_name

name of property to watch for changes, or NULL to watch all properties

include_value

whether to include the new property value in the message

Returns

a watch id, which can be used in connection with remove_property_notify_watch() to remove the watch again.

fn add_property_notify_watch( &self, property_name: Option<&str>, include_value: bool, ) -> NotifyWatchId

property_name

name of property to watch for changes, or NULL to watch all properties

include_value

whether to include the new property value in the message

Returns

a watch id, which can be used in connection with remove_property_notify_watch() to remove the watch again.

fn remove_property_notify_watch(&self, watch_id: NotifyWatchId)

watch_id

watch id to remove

fn query_convert<U: SpecificFormattedValueFullRange>( &self, src_val: impl FormattedValue, ) -> Option<U>

Queries an element to convert src_val in src_format to dest_format.

src_format

a Format to convert from.

src_val

a value to convert.

dest_format

the Format to convert to.

Returns

true if the query could be performed.

dest_val

a pointer to the result.

fn query_convert_generic( &self, src_val: impl FormattedValue, dest_format: Format, ) -> Option<GenericFormattedValue>

fn query_duration<T: SpecificFormattedValueIntrinsic>(&self) -> Option<T>

Queries an element (usually top-level pipeline or playbin element) for the total stream duration in nanoseconds. This query will only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application will receive an ASYNC_DONE message on the pipeline bus when that is the case.

If the duration changes for some reason, you will get a DURATION_CHANGED message on the pipeline bus, in which case you should re-query the duration using this function.

format

the Format requested

Returns

true if the query could be performed.

duration

A location in which to store the total duration, or None.

fn query_duration_generic( &self, format: Format, ) -> Option<GenericFormattedValue>

fn query_position<T: SpecificFormattedValueIntrinsic>(&self) -> Option<T>

Queries an element (usually top-level pipeline or playbin element) for the stream position in nanoseconds. This will be a value between 0 and the stream duration (if the stream duration is known). This query will usually only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application will receive an ASYNC_DONE message on the pipeline bus when that is the case.

If one repeatedly calls this function one can also create a query and reuse it in query().

format

the Format requested

Returns

true if the query could be performed.

cur

a location in which to store the current position, or None.

fn query_position_generic( &self, format: Format, ) -> Option<GenericFormattedValue>

fn seek<V: FormattedValue>( &self, rate: f64, flags: SeekFlags, start_type: SeekType, start: V, stop_type: SeekType, stop: impl CompatibleFormattedValue<V>, ) -> Result<(), BoolError>

Sends a seek event to an element. See gst_event_new_seek() for the details of the parameters. The seek event is sent to the element using send_event().

MT safe.

rate

The new playback rate

format

The format of the seek values

flags

The optional seek flags.

start_type

The type and flags for the new start position

start

The value of the new start position

stop_type

The type and flags for the new stop position

stop

The value of the new stop position

Returns

true if the event was handled. Flushing seeks will trigger a preroll, which will emit GST_MESSAGE_ASYNC_DONE.

fn seek_simple( &self, seek_flags: SeekFlags, seek_pos: impl FormattedValue, ) -> Result<(), BoolError>

Simple API to perform a seek on the given element, meaning it just seeks to the given position relative to the start of the stream. For more complex operations like segment seeks (e.g. for looping) or changing the playback rate or seeking relative to the last configured playback segment you should use seek().

In a completely prerolled PAUSED or PLAYING pipeline, seeking is always guaranteed to return true on a seekable media type or false when the media type is certainly not seekable (such as a live stream).

Some elements allow for seeking in the READY state, in this case they will store the seek event and execute it when they are put to PAUSED. If the element supports seek in READY, it will always return true when it receives the event in the READY state.

format

a Format to execute the seek in, such as Format::Time

seek_flags

seek options; playback applications will usually want to use GST_SEEK_FLAG_FLUSH | GST_SEEK_FLAG_KEY_UNIT here

seek_pos

position to seek to (relative to the start); if you are doing a seek in Format::Time this value is in nanoseconds - multiply with GST_SECOND to convert seconds to nanoseconds or with GST_MSECOND to convert milliseconds to nanoseconds.

Returns

true if the seek operation succeeded. Flushing seeks will trigger a preroll, which will emit GST_MESSAGE_ASYNC_DONE.

fn call_async<F>(&self, func: F)

where F: FnOnce(&Self) + Send + 'static,

Calls func from another thread and passes user_data to it. This is to be used for cases when a state change has to be performed from a streaming thread, directly via ElementExt::set_state() or indirectly e.g. via SEEK events.

Calling those functions directly from the streaming thread will cause deadlocks in many situations, as they might involve waiting for the streaming thread to shut down from this very streaming thread.

MT safe.

func

Function to call asynchronously from another thread

destroy_notify

GDestroyNotify for user_data

fn call_async_future<F, T>( &self, func: F, ) -> Pin<Box<dyn Future<Output = T> + Send + 'static>>

where F: FnOnce(&Self) -> T + Send + 'static, T: Send + 'static,

fn current_running_time(&self) -> Option<ClockTime>

Returns the running time of the element. The running time is the element’s clock time minus its base time. Will return GST_CLOCK_TIME_NONE if the element has no clock, or if its base time has not been set.

Returns

the running time of the element, or GST_CLOCK_TIME_NONE if the element has no clock or its base time has not been set.

fn current_clock_time(&self) -> Option<ClockTime>

Returns the current clock time of the element, as in, the time of the element’s clock, or GST_CLOCK_TIME_NONE if there is no clock.

Returns

the clock time of the element, or GST_CLOCK_TIME_NONE if there is no clock.

fn request_pad_simple(&self, name: &str) -> Option<Pad>

The name of this function is confusing to people learning GStreamer. request_pad_simple() aims at making it more explicit it is a simplified ElementExt::request_pad().

Deprecated since 1.20

Prefer using request_pad_simple() which provides the exact same functionality.

name

the name of the request Pad to retrieve.

Returns

requested Pad if found, otherwise None. Release after usage.

fn link(&self, dest: &impl IsA<Element>) -> Result<(), BoolError>

Links self to dest. The link must be from source to destination; the other direction will not be tried. The function looks for existing pads that aren’t linked yet. It will request new pads if necessary. Such pads need to be released manually when unlinking. If multiple links are possible, only one is established.

Make sure you have added your elements to a bin or pipeline with GstBinExt::add() before trying to link them.

dest

the Element containing the destination pad.

Returns

true if the elements could be linked, false otherwise.

fn link_filtered( &self, dest: &impl IsA<Element>, filter: &Caps, ) -> Result<(), BoolError>

Links self to dest using the given caps as filtercaps. The link must be from source to destination; the other direction will not be tried. The function looks for existing pads that aren’t linked yet. It will request new pads if necessary. If multiple links are possible, only one is established.

Make sure you have added your elements to a bin or pipeline with GstBinExt::add() before trying to link them.

dest

the Element containing the destination pad.

filter

the Caps to filter the link, or None for no filter.

Returns

true if the pads could be linked, false otherwise.

fn link_pads( &self, srcpadname: Option<&str>, dest: &impl IsA<Element>, destpadname: Option<&str>, ) -> Result<(), BoolError>

Links the two named pads of the source and destination elements. Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails.

srcpadname

the name of the Pad in source element or None for any pad.

dest

the Element containing the destination pad.

destpadname

the name of the Pad in destination element, or None for any pad.

Returns

true if the pads could be linked, false otherwise.

fn link_pads_filtered( &self, srcpadname: Option<&str>, dest: &impl IsA<Element>, destpadname: Option<&str>, filter: &Caps, ) -> Result<(), BoolError>

Links the two named pads of the source and destination elements. Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails. If caps is not None, makes sure that the caps of the link is a subset of caps.

srcpadname

the name of the Pad in source element or None for any pad.

dest

the Element containing the destination pad.

destpadname

the name of the Pad in destination element or None for any pad.

filter

the Caps to filter the link, or None for no filter.

Returns

true if the pads could be linked, false otherwise.

fn link_pads_full( &self, srcpadname: Option<&str>, dest: &impl IsA<Element>, destpadname: Option<&str>, flags: PadLinkCheck, ) -> Result<(), BoolError>

Links the two named pads of the source and destination elements. Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails.

Calling link_pads_full() with flags == PadLinkCheck::DEFAULT is the same as calling link_pads() and the recommended way of linking pads with safety checks applied.

This is a convenience function for PadExt::link_full().

srcpadname

the name of the Pad in source element or None for any pad.

dest

the Element containing the destination pad.

destpadname

the name of the Pad in destination element, or None for any pad.

flags

the PadLinkCheck to be performed when linking pads.

Returns

true if the pads could be linked, false otherwise.

Object Safety

This trait is not object safe.

Implementors

impl<O: IsA<Element>> ElementExtManual for O