Struct gstreamer::structure::Structure

pub struct Structure(_);

A crate::Structure is a collection of key/value pairs. The keys are expressed as GQuarks and the values can be of any GType.

In addition to the key/value pairs, a crate::Structure also has a name. The name starts with a letter and can be filled by letters, numbers and any of “/-_.:”.

crate::Structure is used by various GStreamer subsystems to store information in a flexible and extensible way. A crate::Structure does not have a refcount because it usually is part of a higher level object such as crate::Caps, crate::Message, crate::Event, crate::Query. It provides a means to enforce mutability using the refcount of the parent with the [Self::set_parent_refcount()] method.

A crate::Structure can be created with Self::new_empty() or Self::new(), which both take a name and an optional set of key/value pairs along with the types of the values.

Field values can be changed with [Self::set_value()] or [Self::set()].

Field values can be retrieved with [Self::get_value()] or the more convenient gst_structure_get_*() functions.

Fields can be removed with [Self::remove_field()] or [Self::remove_fields()].

Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not allowed. Strings may be None however.

The serialization format

GstStructure serialization format serialize the GstStructure name, keys/GType/values in a comma separated list with the structure name as first field without value followed by separated key/value pairs in the form key=value, for example:

a-structure, key=value

The values type will be inferred if not explicitly specified with the (GTypeName)value syntax, for example the following struct will have one field called ‘is-string’ which has the string ‘true’ as a value:

a-struct, field-is-string=(string)true, field-is-boolean=true

Note: without specifying (string), field-is-string` type would have been inferred as boolean.

Note: we specified (string) as a type even if gchararray is the actual GType name as for convenience some well known types have been aliased or abbreviated.

To avoid specifying the type, you can give some hints to the “type system”. For example to specify a value as a double, you should add a decimal (ie. 1 is an int while 1.0 is a double).

Note: when a structure is serialized with [Self::to_string], all values are explicitly typed.

Some types have special delimiters:

• GstValueArray are inside curly brackets ({ and }). For example a-structure, array={1, 2, 3}
• Ranges are inside brackets ([ and ]). For example a-structure, range=[1, 6, 2] 1 being the min value, 6 the maximum and 2 the step. To specify a GST_TYPE_INT64_RANGE you need to explicitly specify it like: a-structure, a-int64-range=(gint64) [1, 5]
• GstValueList are inside “less and greater than” (< and >). For example `a-structure, list=<1, 2, 3>

Structures are delimited either by a null character \0 or a semicolumn ; the latter allowing to store multiple structures in the same string (see #GstCaps).

Quotes are used as “default” delimiters and can be used around any types that don’t use other delimiters (for example a-struct, i=(int)"1"). They are use to allow adding spaces or special characters (such as delimiters, semicolumns, etc..) inside strings and you can use backslashes \ to escape characters inside them, for example:

a-struct, special="\"{[(;)]}\" can be used inside quotes"

They also allow for nested structure, such as:

a-struct, nested=(GstStructure)"nested-struct, nested=true"

Note: Be aware that the current #GstCaps / #GstStructure serialization into string has limited support for nested #GstCaps / #GstStructure fields. It can only support one level of nesting. Using more levels will lead to unexpected behavior when using serialization features, such as gst_caps_to_string() or gst_value_serialize() and their counterparts.

Implementations

impl Structure

pub fn builder(name: &str) -> Builder

pub fn new_empty(name: &str) -> Structure

Creates a new, empty crate::Structure with the given name.

See [Self::set_name()] for constraints on the name parameter.

Free-function: gst_structure_free

name

name of new structure

Returns

a new, empty crate::Structure

pub fn new(
    name: &str,
    values: &[(&str, &(dyn ToSendValue + Sync))]
) -> Structure

Creates a new crate::Structure with the given name. Parses the list of variable arguments and sets fields to the values listed. Variable arguments should be passed as field name, field type, and value. Last variable argument should be None.

Free-function: gst_structure_free

name

name of new structure

firstfield

name of first field to set

Returns

a new crate::Structure

pub unsafe fn into_ptr(self) -> *mut GstStructure

pub fn from_iter<'a, 'b, I>(name: &str, iter: I) -> Structure where
    I: IntoIterator<Item = (&'a str, &'b SendValue)>, 

Methods from Deref<Target = StructureRef>

pub unsafe fn as_ptr(&self) -> *const GstStructure

pub unsafe fn as_mut_ptr(&self) -> *mut GstStructure

pub fn get<'a, T: FromValue<'a>>(&'a self, name: &str) -> Result<T, GetError> where
    <<T as FromValue<'a>>::Checker as ValueTypeChecker>::Error: GlibValueError, 

pub fn get_optional<'a, T: FromValue<'a>>(
    &'a self,
    name: &str
) -> Result<Option<T>, GetError> where
    <<T as FromValue<'a>>::Checker as ValueTypeChecker>::Error: GlibValueError, 

pub fn value(&self, name: &str) -> Result<&SendValue, GetError>

pub fn get_by_quark<'a, T: FromValue<'a>>(
    &'a self,
    name: Quark
) -> Result<T, GetError> where
    <<T as FromValue<'a>>::Checker as ValueTypeChecker>::Error: GlibValueError, 

pub fn get_optional_by_quark<'a, T: FromValue<'a>>(
    &'a self,
    name: Quark
) -> Result<Option<T>, GetError> where
    <<T as FromValue<'a>>::Checker as ValueTypeChecker>::Error: GlibValueError, 

pub fn value_by_quark(&self, name: Quark) -> Result<&SendValue, GetError>

pub fn set<T: ToSendValue + Sync>(&mut self, name: &str, value: T)

pub fn set_value(&mut self, name: &str, value: SendValue)

pub fn set_by_quark<T: ToSendValue + Sync>(&mut self, name: Quark, value: T)

pub fn set_value_by_quark(&mut self, name: Quark, value: SendValue)

pub fn name<'a>(&self) -> &'a str

pub fn name_quark(&self) -> Quark

pub fn set_name(&mut self, name: &str)

pub fn has_field(&self, field: &str) -> bool

pub fn has_field_with_type(&self, field: &str, type_: Type) -> bool

pub fn has_field_by_quark(&self, field: Quark) -> bool

pub fn has_field_with_type_by_quark(&self, field: Quark, type_: Type) -> bool

pub fn remove_field(&mut self, field: &str)

pub fn remove_fields(&mut self, fields: &[&str])

pub fn remove_all_fields(&mut self)

pub fn fields(&self) -> FieldIterator<'_>

pub fn iter(&self) -> Iter<'_>

pub fn nth_field_name<'a>(&self, idx: u32) -> Option<&'a str>

pub fn n_fields(&self) -> u32

pub fn can_intersect(&self, other: &StructureRef) -> bool

pub fn intersect(&self, other: &StructureRef) -> Option<Structure>

pub fn is_subset(&self, superset: &StructureRef) -> bool

pub fn fixate(&mut self)

pub fn fixate_field(&mut self, name: &str) -> bool

pub fn fixate_field_bool(&mut self, name: &str, target: bool) -> bool

pub fn fixate_field_str(&mut self, name: &str, target: &str) -> bool

pub fn fixate_field_nearest_double(&mut self, name: &str, target: f64) -> bool

pub fn fixate_field_nearest_fraction<T: Into<Fraction>>(
    &mut self,
    name: &str,
    target: T
) -> bool

pub fn fixate_field_nearest_int(&mut self, name: &str, target: i32) -> bool

Trait Implementations

impl AsMut<StructureRef> for Structure

fn as_mut(&mut self) -> &mut StructureRef

Performs the conversion.

impl AsRef<StructureRef> for Structure

fn as_ref(&self) -> &StructureRef

Performs the conversion.

impl Borrow<StructureRef> for Structure

fn borrow(&self) -> &StructureRef

Immutably borrows from an owned value.

impl BorrowMut<StructureRef> for Structure

fn borrow_mut(&mut self) -> &mut StructureRef

Mutably borrows from an owned value.

impl Clone for Structure

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Structure

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for Structure

type Target = StructureRef

The resulting type after dereferencing.

fn deref(&self) -> &StructureRef

Dereferences the value.

impl DerefMut for Structure

fn deref_mut(&mut self) -> &mut StructureRef

Mutably dereferences the value.

impl<'de> Deserialize<'de> for Structure

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for Structure

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Structure

fn drop(&mut self)

Executes the destructor for this type.

impl FromGlibPtrFull<*const GstStructure> for Structure

unsafe fn from_glib_full(ptr: *const GstStructure) -> Self

Safety

impl FromGlibPtrFull<*mut GstStructure> for Structure

unsafe fn from_glib_full(ptr: *mut GstStructure) -> Self

Safety

impl FromGlibPtrNone<*const GstStructure> for Structure

unsafe fn from_glib_none(ptr: *const GstStructure) -> Self

Safety

impl FromGlibPtrNone<*mut GstStructure> for Structure

unsafe fn from_glib_none(ptr: *mut GstStructure) -> Self

Safety

impl FromStr for Structure

type Err = BoolError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<'a> FromValue<'a> for Structure

type Checker = GenericValueTypeOrNoneChecker<Self>

Value type checker.

unsafe fn from_value(value: &'a Value) -> Self

Get the contained value from a Value.

impl GlibPtrDefault for Structure

type GlibType = *mut GstStructure

impl PartialEq<Structure> for Structure

fn eq(&self, other: &Structure) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<StructureRef> for Structure

fn eq(&self, other: &StructureRef) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Serialize for Structure

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StaticType for Structure

fn static_type() -> Type

Returns the type identifier of Self.

impl<'a> ToGlibPtr<'a, *const GstStructure> for Structure

type Storage = &'a Self

fn to_glib_none(&'a self) -> Stash<'a, *const GstStructure, Self>

Transfer: none.

fn to_glib_full(&self) -> *const GstStructure

Transfer: full.

fn to_glib_container(&'a self) -> Stash<'a, P, Self>

Transfer: container.

impl<'a> ToGlibPtr<'a, *mut GstStructure> for Structure

type Storage = &'a Self

fn to_glib_none(&'a self) -> Stash<'a, *mut GstStructure, Self>

Transfer: none.

fn to_glib_full(&self) -> *mut GstStructure

Transfer: full.

fn to_glib_container(&'a self) -> Stash<'a, P, Self>

Transfer: container.

impl<'a> ToGlibPtrMut<'a, *mut GstStructure> for Structure

type Storage = &'a mut Self

fn to_glib_none_mut(&'a mut self) -> StashMut<'_, *mut GstStructure, Self>

Transfer: none.

impl ToValue for Structure

fn to_value(&self) -> Value

Convert a value to a Value.

fn value_type(&self) -> Type

Returns the type identifer of self.

impl ToValueOptional for Structure

fn to_value_optional(s: Option<&Self>) -> Value

Convert an Option to a Value.

impl ValueType for Structure

type Type = Self

Type to get the Type from.

impl Eq for Structure

impl Send for Structure

impl Sync for Structure