gstreamermm  1.10.0
Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | Related Functions | List of all members
Gst::Structure Class Reference

Generic class containing fields of names and values. More...

#include <gstreamermm/structure.h>

Public Types

typedef sigc::slot< bool, const Glib::ustring&, const Glib::ValueBase& > SlotForeach
 For example, bool on_foreach(const Glib::ustring& id, const Glib::ValueBase& value);. More...
 
typedef sigc::slot< bool, const Glib::ustring&, Glib::ValueBase& > SlotMap
 For example, bool on_map(const Glib::ustring& id, Glib::ValueBase& value);. More...
 

Public Member Functions

 Structure ()
 
 Structure (GstStructure* gobject, bool make_a_copy=true)
 
 Structure (const Structure& other)
 
Structureoperator= (const Structure& other)
 
 Structure (Structure&& other) noexcept
 
Structureoperator= (Structure&& other) noexcept
 
 ~Structure () noexcept
 
void swap (Structure& other) noexcept
 
GstStructure* gobj ()
 Provides access to the underlying C instance. More...
 
const GstStructure* gobj () const
 Provides access to the underlying C instance. More...
 
GstStructure* gobj_copy () const
 Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs. More...
 
template<class ... DataTypes>
 Structure (const Glib::ustring& name, DataTypes... data)
 Creates a Structure with the given name. More...
 
 operator const void* () const
 Use this to discover if the Structure is a valid object. More...
 
GstStructure* release () noexcept
 Release the ownership of underlying GstStructure instance. More...
 
Glib::ustring get_name () const
 Get the name of structure as a string. More...
 
bool has_name (const Glib::ustring& name) const
 Checks if the structure has the given name. More...
 
void set_name (const Glib::ustring& name)
 Sets the name of the structure to the given name. More...
 
Glib::QueryQuark get_name_id () const
 Get the name of structure as a GQuark. More...
 
void remove_all_fields ()
 Removes all fields in a GstStructure. More...
 
GType get_field_type (const Glib::ustring& fieldname) const
 Finds the field with the given name, and returns the type of the value it contains. More...
 
int size () const
 Get the number of fields in the structure. More...
 
Glib::ustring get_nth_field_name (guint index) const
 Get the name of the given field number, counting from 0 onwards. More...
 
Glib::ustring to_string () const
 Converts structure to a human-readable string representation. More...
 
bool fixate_field_nearest_int (const Glib::ustring& name, int target)
 Fixates a Gst::Structure by changing the given field to the nearest integer to target that is a subset of the existing field. More...
 
bool fixate_field_nearest_double (const Glib::ustring& name, double target)
 Fixates a Gst::Structure by changing the given field to the nearest double to target that is a subset of the existing field. More...
 
bool fixate_field_string (const Glib::ustring& name, const Glib::ustring& target)
 Fixates a Gst::Structure by changing the given name field to the given target string if that field is not fixed yet. More...
 
bool fixate_field (const Glib::ustring& name)
 Fixates a Gst::Structure by changing the given field with its fixated value. More...
 
bool fixate_field_boolean (const Glib::ustring& name, bool target)
 Fixates a Gst::Structure by changing the given name field to the given target boolean if that field is not fixed yet. More...
 
Gst::Structure intersect (const Gst::Structure& struct2) const
 Intersects struct1 and struct2 and returns the intersection. More...
 
bool is_equal (const Gst::Structure& struct2) const
 Tests if the two Gst::Structure are equal. More...
 
bool is_subset (const Gst::Structure& superset) const
 Checks if subset is a subset of superset, i.e. has the same structure name and for all fields that are existing in superset, subset has a value that is a subset of the value in superset. More...
 
bool can_intersect (const Gst::Structure& struct2) const
 Tries intersecting struct1 and struct2 and reports whether the result would not be empty. More...
 
void fixate ()
 Fixate all values in structure using gst_value_fixate(). More...
 
bool get_flagset (const Glib::ustring& fieldname, guint& value_flags, guint& value_mask) const
 Read the GstFlagSet flags and mask out of the structure into the provided pointers. More...
 
bool has_field (const Glib::ustring& fieldname) const
 Check if structure contains a field named fieldname. More...
 
bool has_field (const Glib::ustring& fieldname, GType type) const
 Check if structure contains a field named fieldname and with GType type. More...
 
void get_field (const Glib::ustring& fieldname, Glib::ValueBase& value) const
 Get the value of the field with name fieldname. More...
 
template<typename DataType >
void get_field (const Glib::ustring& fieldname, Glib::Value< DataType >& value) const
 Get the value of the field with name fieldname. More...
 
bool get_field (const Glib::ustring& fieldname, GType enumtype, int& value) const
 Gets the value of field fieldname with GType enum type enumtype into integer value. More...
 
template<typename DataType >
bool get_field (const Glib::ustring& fieldname, DataType& value) const
 Gets the value of field fieldname into DataType value. More...
 
void set_field (const Glib::ustring& fieldname, const Glib::ValueBase& value)
 Sets the field with name fieldname to value. More...
 
template<typename DataType >
void set_field (const Glib::ustring& fieldname, const Glib::Value< DataType >& value)
 Sets the field with name fieldname to value. More...
 
void set_field (const Glib::ustring& fieldname, const char* value)
 Sets the field with name fieldname to value. More...
 
template<class DataType , class ... DataTypes>
void set_fields (const Glib::ustring& fieldname, const DataType& value, DataTypes ...further_data)
 Sets the fields with name fieldname to values. More...
 
void set_field (const Glib::ustring& fieldname, GType enumtype, int value)
 Sets the field with name fieldname to the value value of the enum type enum_type. More...
 
template<typename DataType >
void set_field (const Glib::ustring& fieldname, const DataType& value)
 Sets the field with name fieldname field to the DataType value. More...
 
void remove_field (const Glib::ustring& fieldname)
 Removes the field with name fieldname. More...
 
bool foreach (const SlotForeach& slot)
 Calls the provided slot once for each field in the Gst::Structure. More...
 
bool map_in_place (const SlotMap& slot)
 Calls the provided slot once for each field in the Gst::Structure. More...
 
bool fixate_nearest_fraction (const Glib::ustring& field_name, const Gst::Fraction& target)
 Fixates a Gst::Structure by changing the given field to the nearest fraction to given Gst::Fraction that is a subset of the existing field. More...
 

Static Public Member Functions

static GType get_type ()
 Get the GType for this class, for use with the underlying GObject type system. More...
 
static Structure create_from_string (const Glib::ustring& the_string)
 Creates a Gst::Structure from a string representation. More...
 

Protected Attributes

GstStructure* gobject_
 

Related Functions

(Note that these are not member functions.)

void swap (Structure& lhs, Structure& rhs) noexcept
 
Gst::Structure wrap (GstStructure* object, bool take_copy=false)
 A Glib::wrap() method for this object. More...
 

Detailed Description

Generic class containing fields of names and values.

A Gst::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 Gst::Structure also has a name. The name starts with a letter and can be filled by letters, numbers and any of "/-_.:".

Gst::Structure is used by various GStreamer subsystems to store information in a flexible and extensible way. A Gst::Structure does not have a refcount because it usually is part of a higher level object such as Gst::Caps, Gst::Message, Gst::Event, Gst::Query.

A Gst::Structure can be created with constructor, which take a name and an optional set of key/value pairs along with the types of the values.

Field values can be changed with set_field() or set_fields().

Field values can be retrieved with gst_get_field().

Fields can be removed with remove_field().

Strings in structures must be ASCII or UTF-8 encoded.

Be aware that the current Gst::Caps / Gst::Structure serialization into string has limited support for nested Gst::Caps / Gst::Structure 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.

Last reviewed on 2016-07-12 (1.8.0)

Member Typedef Documentation

◆ SlotForeach

typedef sigc::slot<bool, const Glib::ustring&, const Glib::ValueBase&> Gst::Structure::SlotForeach

For example, bool on_foreach(const Glib::ustring& id, const Glib::ValueBase& value);.

The on_foreach function should return true if the foreach operation should continue, or false if the operation should stop with false.

◆ SlotMap

typedef sigc::slot<bool, const Glib::ustring&, Glib::ValueBase&> Gst::Structure::SlotMap

For example, bool on_map(const Glib::ustring& id, Glib::ValueBase& value);.

The map function should return true if the map operation should continue, or false if the operation should stop with false.

Constructor & Destructor Documentation

◆ Structure() [1/5]

Gst::Structure::Structure ( )

◆ Structure() [2/5]

Gst::Structure::Structure ( GstStructure *  gobject,
bool  make_a_copy = true 
)
explicit

◆ Structure() [3/5]

Gst::Structure::Structure ( const Structure other)

◆ Structure() [4/5]

Gst::Structure::Structure ( Structure&&  other)
noexcept

◆ ~Structure()

Gst::Structure::~Structure ( )
noexcept

◆ Structure() [5/5]

template <class ... DataTypes>
Gst::Structure::Structure ( const Glib::ustring &  name,
DataTypes...  data 
)
explicit

Creates a 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 and value

Member Function Documentation

◆ can_intersect()

bool Gst::Structure::can_intersect ( const Gst::Structure struct2) const

Tries intersecting struct1 and struct2 and reports whether the result would not be empty.

Parameters
struct2A Gst::Structure.
Returns
true if intersection would not be empty.

◆ create_from_string()

static Structure Gst::Structure::create_from_string ( const Glib::ustring &  the_string)
static

Creates a Gst::Structure from a string representation.

Parameters
the_stringA string representation of a Gst::Structure. See to_string().
Returns
A Structure. This will be invalid (see operator=) when the string could not be parsed.

◆ fixate()

void Gst::Structure::fixate ( )

Fixate all values in structure using gst_value_fixate().

structure will be modified in-place and should be writable.

◆ fixate_field()

bool Gst::Structure::fixate_field ( const Glib::ustring &  name)

Fixates a Gst::Structure by changing the given field with its fixated value.

Parameters
nameA field in structure.
Returns
true if the structure field could be fixated.

◆ fixate_field_boolean()

bool Gst::Structure::fixate_field_boolean ( const Glib::ustring &  name,
bool  target 
)

Fixates a Gst::Structure by changing the given name field to the given target boolean if that field is not fixed yet.

Parameters
nameA field in structure.
targetThe target value of the fixation.
Returns
true if the structure could be fixated.

◆ fixate_field_nearest_double()

bool Gst::Structure::fixate_field_nearest_double ( const Glib::ustring &  name,
double  target 
)

Fixates a Gst::Structure by changing the given field to the nearest double to target that is a subset of the existing field.

Parameters
nameA field in structure.
targetThe target value of the fixation.
Returns
true if the structure could be fixated.

◆ fixate_field_nearest_int()

bool Gst::Structure::fixate_field_nearest_int ( const Glib::ustring &  name,
int  target 
)

Fixates a Gst::Structure by changing the given field to the nearest integer to target that is a subset of the existing field.

Parameters
nameA field in structure.
targetThe target value of the fixation.
Returns
true if the structure could be fixated.

◆ fixate_field_string()

bool Gst::Structure::fixate_field_string ( const Glib::ustring &  name,
const Glib::ustring &  target 
)

Fixates a Gst::Structure by changing the given name field to the given target string if that field is not fixed yet.

Parameters
nameA field in structure.
targetThe target value of the fixation.
Returns
true if the structure could be fixated.

◆ fixate_nearest_fraction()

bool Gst::Structure::fixate_nearest_fraction ( const Glib::ustring &  field_name,
const Gst::Fraction target 
)

Fixates a Gst::Structure by changing the given field to the nearest fraction to given Gst::Fraction that is a subset of the existing field.

Parameters
field_nameA field in structure.
targetThe target value of the fixation.
Returns
true If the structure could be fixated.

◆ foreach()

bool Gst::Structure::foreach ( const SlotForeach slot)

Calls the provided slot once for each field in the Gst::Structure.

The slot must not modify the fields. See also map_in_place().

Parameters
slotA slot to call for each field.
Returns
true if the supplied slot returns true For each of the fields, false otherwise.

◆ get_field() [1/4]

void Gst::Structure::get_field ( const Glib::ustring &  fieldname,
Glib::ValueBase &  value 
) const

Get the value of the field with name fieldname.

Parameters
fieldnameThe name of the field to get.
valueThe Value class in which to store the value.

◆ get_field() [2/4]

template <typename DataType >
void Gst::Structure::get_field ( const Glib::ustring &  fieldname,
Glib::Value< DataType > &  value 
) const

Get the value of the field with name fieldname.

Parameters
fieldnameThe name of the field to get.
valueThe Value class in which to store the value.

◆ get_field() [3/4]

bool Gst::Structure::get_field ( const Glib::ustring &  fieldname,
GType  enumtype,
int &  value 
) const

Gets the value of field fieldname with GType enum type enumtype into integer value.

Caller is responsible for making sure the field exists and has the correct type. A call to this method would look like so:

...
int state;
structure.get_field("state", Glib::Value<Gst::State>::value_type(),
state);
...
Parameters
fieldnameThe name of a field.
enumtypeThe enum GType of the field.
valueAn output parameter that will be set with the value.
Returns
true if value could be set correctly. If there was no field with fieldname or the existing field did not contain an enum, this function returns false.

◆ get_field() [4/4]

template <typename DataType >
bool Gst::Structure::get_field ( const Glib::ustring &  fieldname,
DataType &  value 
) const

Gets the value of field fieldname into DataType value.

The caller is responsible for making sure the field exists and has the correct type.

Parameters
fieldnameThe name of a field.
valueThe DataType to set.

◆ get_field_type()

GType Gst::Structure::get_field_type ( const Glib::ustring &  fieldname) const

Finds the field with the given name, and returns the type of the value it contains.

If the field is not found, G_TYPE_INVALID is returned.

Parameters
fieldnameThe name of the field.
Returns
The Value of the field.

◆ get_flagset()

bool Gst::Structure::get_flagset ( const Glib::ustring &  fieldname,
guint &  value_flags,
guint &  value_mask 
) const

Read the GstFlagSet flags and mask out of the structure into the provided pointers.

Parameters
fieldnameThe name of a field.
value_flagsA pointer to a unsigned int for the flags field.
value_maskA pointer to a unsigned int for the mask field.
Returns
true if the values could be set correctly. If there was no field with fieldname or the existing field did not contain a GstFlagSet, this function returns false.

◆ get_name()

Glib::ustring Gst::Structure::get_name ( ) const

Get the name of structure as a string.

Returns
The name of the structure.

◆ get_name_id()

Glib::QueryQuark Gst::Structure::get_name_id ( ) const

Get the name of structure as a GQuark.

Returns
The quark representing the name of the structure.

◆ get_nth_field_name()

Glib::ustring Gst::Structure::get_nth_field_name ( guint  index) const

Get the name of the given field number, counting from 0 onwards.

Parameters
indexThe index to get the name of.
Returns
The name of the given field number.

◆ get_type()

static GType Gst::Structure::get_type ( )
static

Get the GType for this class, for use with the underlying GObject type system.

◆ gobj() [1/2]

GstStructure* Gst::Structure::gobj ( )
inline

Provides access to the underlying C instance.

◆ gobj() [2/2]

const GstStructure* Gst::Structure::gobj ( ) const
inline

Provides access to the underlying C instance.

◆ gobj_copy()

GstStructure* Gst::Structure::gobj_copy ( ) const

Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.

◆ has_field() [1/2]

bool Gst::Structure::has_field ( const Glib::ustring &  fieldname) const

Check if structure contains a field named fieldname.

Parameters
fieldnameThe name of a field.
Returns
true if the structure contains a field with the given name.

◆ has_field() [2/2]

bool Gst::Structure::has_field ( const Glib::ustring &  fieldname,
GType  type 
) const

Check if structure contains a field named fieldname and with GType type.

Parameters
fieldnameThe name of a field.
typeThe type of a value.
Returns
true if the structure contains a field with the given name and type.

◆ has_name()

bool Gst::Structure::has_name ( const Glib::ustring &  name) const

Checks if the structure has the given name.

Parameters
nameStructure name to check for.
Returns
true if name matches the name of the structure.

◆ intersect()

Gst::Structure Gst::Structure::intersect ( const Gst::Structure struct2) const

Intersects struct1 and struct2 and returns the intersection.

Parameters
struct2A Gst::Structure.
Returns
Intersection of struct1 and struct2.

◆ is_equal()

bool Gst::Structure::is_equal ( const Gst::Structure struct2) const

Tests if the two Gst::Structure are equal.

Parameters
struct2A Gst::Structure.
Returns
true if the two structures have the same name and field.

◆ is_subset()

bool Gst::Structure::is_subset ( const Gst::Structure superset) const

Checks if subset is a subset of superset, i.e. has the same structure name and for all fields that are existing in superset, subset has a value that is a subset of the value in superset.

Parameters
supersetA potentially greater Gst::Structure.
Returns
true if subset is a subset of superset.

◆ map_in_place()

bool Gst::Structure::map_in_place ( const SlotMap slot)

Calls the provided slot once for each field in the Gst::Structure.

In contrast to foreach(), the function may modify but not delete the fields. The structure must be mutable.

Parameters
slotA slot to call for each field.
Returns
true if the supplied slot returns true For each of the fields, false otherwise.

◆ operator const void *()

Gst::Structure::operator const void * ( ) const

Use this to discover if the Structure is a valid object.

◆ operator=() [1/2]

Structure& Gst::Structure::operator= ( const Structure other)

◆ operator=() [2/2]

Structure& Gst::Structure::operator= ( Structure&&  other)
noexcept

◆ release()

GstStructure* Gst::Structure::release ( )
noexcept

Release the ownership of underlying GstStructure instance.

Gst::Structure's underlying instance is set to nullptr, therefore underlying object can't be accessed through this Gst::Structure anymore.

Returns
an underlying instance of GstStructure object.

Most users should not use release(). It can spoil the automatic destruction of the managed object.

◆ remove_all_fields()

void Gst::Structure::remove_all_fields ( )

Removes all fields in a GstStructure.

◆ remove_field()

void Gst::Structure::remove_field ( const Glib::ustring &  fieldname)

Removes the field with name fieldname.

If the field with the given name does not exist, the structure is unchanged.

Parameters
fieldnameThe name of the field to remove.

◆ set_field() [1/5]

void Gst::Structure::set_field ( const Glib::ustring &  fieldname,
const Glib::ValueBase &  value 
)

Sets the field with name fieldname to value.

If the field does not exist, it is created. If the field exists, the previous value is replaced and freed.

Parameters
fieldnameThe name of the field to set.
valueThe value to set the field to.

◆ set_field() [2/5]

template <typename DataType >
void Gst::Structure::set_field ( const Glib::ustring &  fieldname,
const Glib::Value< DataType > &  value 
)

Sets the field with name fieldname to value.

If the field does not exist, it is created. If the field exists, the previous value is replaced and freed.

Parameters
fieldnameThe name of the field to set.
valueThe value to set the field to.

◆ set_field() [3/5]

void Gst::Structure::set_field ( const Glib::ustring &  fieldname,
const char *  value 
)

Sets the field with name fieldname to value.

If the field does not exist, it is created. If the field exists, the previous value is replaced and freed.

Parameters
fieldnameThe name of the field to set.
valueThe value to set the field to.

◆ set_field() [4/5]

void Gst::Structure::set_field ( const Glib::ustring &  fieldname,
GType  enumtype,
int  value 
)

Sets the field with name fieldname to the value value of the enum type enum_type.

If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. Caller is responsible for making sure that value is a valid enumtype. A call to this method would look like so:

...
structure.set_field("state", Glib::Value<Gst::State>::value_type(),
...
Parameters
fieldnameThe name of the field to set.
enumtypeThe enum GType that value should be treated as.
valueThe value to set the field to.

◆ set_field() [5/5]

template <typename DataType >
void Gst::Structure::set_field ( const Glib::ustring &  fieldname,
const DataType &  value 
)

Sets the field with name fieldname field to the DataType value.

If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. Please note that when setting fields to special types such as Gst::Fourcc and Gst::Fraction and Glib::Date they are converted to the GStreamer GTypes and thus when attempting to get these fields back as GValues, they will have the GStreamer GType.

Parameters
fieldnameThe name of the field to set.
valueThe value to set the field to.

◆ set_fields()

template <class DataType , class ... DataTypes>
void Gst::Structure::set_fields ( const Glib::ustring &  fieldname,
const DataType &  value,
DataTypes ...  further_data 
)

Sets the fields with name fieldname to values.

If one of the fields does not exist, it is created. If the field exists, the previous value is replaced and freed.

Parameters
fieldnameThe name of the field to set.
valueThe value to set the field to.
further_dataList of pairs of the format: fieldname, value.

◆ set_name()

void Gst::Structure::set_name ( const Glib::ustring &  name)

Sets the name of the structure to the given name.

The string provided is copied before being used. It must not be empty, start with a letter and can be followed by letters, numbers and any of "/-_.:".

Parameters
nameThe new name of the structure.

◆ size()

int Gst::Structure::size ( ) const

Get the number of fields in the structure.

Returns
The number of fields in the structure.

◆ swap()

void Gst::Structure::swap ( Structure other)
noexcept

◆ to_string()

Glib::ustring Gst::Structure::to_string ( ) const

Converts structure to a human-readable string representation.

For debugging purposes its easier to do something like this:

[C example ellipted] This prints the structure in human readable form.

The current implementation of serialization will lead to unexpected results when there are nested Gst::Caps / Gst::Structure deeper than one level.

Returns
A pointer to string allocated by Glib::malloc().

Friends And Related Function Documentation

◆ swap()

void swap ( Structure lhs,
Structure rhs 
)
related
Parameters
lhsThe left-hand side
rhsThe right-hand side

◆ wrap()

Gst::Structure wrap ( GstStructure *  object,
bool  take_copy = false 
)
related

A Glib::wrap() method for this object.

Parameters
objectThe C instance.
take_copyFalse if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns
A C++ instance that wraps this C instance.

Member Data Documentation

◆ gobject_

GstStructure* Gst::Structure::gobject_
protected