Gst::Structure Class Reference

Gst::Structure — Generic structure containing fields of names and values. More...

#include <structure.h>

List of all members.

Public Types

typedef sigc::slot< bool,
const Glib::QueryQuark
&, const Glib::ValueBase& > 
SlotForeach
 For example, bool on_foreach(const Glib::QueryQuark& id, const Glib::ValueBase& value); The foreach function should return true if foreach operation should continue, false if operation should stop with false.
typedef sigc::slot< bool,
const Glib::QueryQuark
&, Glib::ValueBase& > 
SlotMap
 For example, bool on_map(const Glib::QueryQuark& id, Glib::ValueBase& value); The map function should return true if map operation should continue, false if operation should stop with false.

Public Member Functions

 Structure ()
 Structure (GstStructure* gobject, bool make_a_copy=false, bool destroy=true)
 Structure (const Structure& other)
Structureoperator= (const Structure& other)
 ~Structure ()
void swap (Structure& other)
GstStructure* gobj ()
 Provides access to the underlying C instance.
const GstStructure* gobj () const
 Provides access to the underlying C instance.
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.
void set_destroy (bool destroy)
 Change whether the wrapper should destroy the underlying gobject or not when the wrapper is deleted.
 Structure (const Glib::ustring& name)
Glib::ustring get_name () const
 Get the name of structure as a string.
bool has_name (const Glib::ustring& name) const
 Checks if the structure has the given name.
void set_name (const Glib::ustring& name)
 Sets the name of the structure to the given name.
Glib::QueryQuark get_name_id () const
 Get the name of structure as a GQuark.
void get_field (const Glib::ustring& fieldname, Glib::ValueBase& value) const
 Get the value of the field with name fieldname.
Structureset_field (const Glib::ustring& fieldname, const Glib::ValueBase& value)
 Sets the field with the given name field to value.
Structureremove_field (const Glib::ustring& fieldname)
 Removes the field with the given name.
void remove_all_fields ()
 Removes all fields in a GstStructure.
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.
bool foreach (const SlotForeach& slot)
 Calls the provided slot once for each field in the Gst::Structure.
int size () const
 Get the number of fields in the structure.
bool has_field (const Glib::ustring& fieldname) const
 Check if structure contains a field named fieldname.
bool has_field (const Glib::ustring& fieldname, GType type) const
 Check if structure contains a field named fieldname and with GType type.
bool get_boolean (const Glib::ustring& fieldname, Glib::ValueBase& value) const
 Sets the GValue of value to the boolean value of the given field.
bool get_int (const Glib::ustring& fieldname, Glib::ValueBase& value) const
 Sets the GValue of value to the int value of the given field.
bool get_uint (const Glib::ustring& fieldname, Glib::ValueBase& value) const
 Sets the GValue of value to the uint value of the given field.
bool get_fourcc (const Glib::ustring& fieldname, Glib::ValueBase& value) const
 Sets the GValue of value to the fourc value of the given field.
bool get_double (const Glib::ustring& fieldname, Glib::ValueBase& value) const
 Sets the GValue of value to the double value of the given field.
bool get_string (const Glib::ustring& fieldname, Glib::ValueBase& value) const
 Sets the GValue of value to the string value of the given field.
bool get_date (const Glib::ustring& fieldname, Glib::Date& value) const
 Sets the GValue of value to the GDate value of the given field.
bool get_clock_time (const Glib::ustring& fieldname, Glib::ValueBase& value) const
 Sets the GValue of value to the Gst::ClockTime value of the given field.
bool get_enum (const Glib::ustring& fieldname, GType enumtype, Glib::ValueBase& value) const
 Sets the GValue of value to the enum value of the given field.
bool get_fraction (const Glib::ustring& fieldname, Gst::Fraction& fraction) const
 Sets the GValue of value to the Gst::Fraction value of the given field.
bool map_in_place (const SlotMap& slot)
 Calls the provided slot once for each field in the Gst::Structure.
Glib::ustring nth_field_name (guint index) const
 Get the name of the given field number, counting from 0 onwards.
Glib::ustring to_string () const
 Converts structure to a human-readable string representation.

Static Public Member Functions

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

Protected Attributes

GstStructure* gobject_

Related Functions

(Note that these are not member functions.)

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


Detailed Description

Gst::Structure — Generic structure 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 folled 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. It provides a means to enforce mutability using the refcount of the parent.

Last reviewed on 2007-10-16 (0.10.15)


Member Typedef Documentation

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

For example, bool on_foreach(const Glib::QueryQuark& id, const Glib::ValueBase& value); The foreach function should return true if foreach operation should continue, false if operation should stop with false.

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

For example, bool on_map(const Glib::QueryQuark& id, Glib::ValueBase& value); The map function should return true if map operation should continue, false if operation should stop with false.


Constructor & Destructor Documentation

Gst::Structure::Structure (  ) 

Gst::Structure::Structure ( GstStructure *  gobject,
bool  make_a_copy = false,
bool  destroy = true 
) [explicit]

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

Gst::Structure::~Structure (  ) 

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


Member Function Documentation

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

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

Referenced by swap().

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

Provides access to the underlying C instance.

References gobject_.

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

Provides access to the underlying C instance.

References gobject_.

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.

void Gst::Structure::set_destroy ( bool  destroy  ) 

Change whether the wrapper should destroy the underlying gobject or not when the wrapper is deleted.

Parameters:
destroy whether or not the wrapper should destroy the underlying gobject when it is destroyed

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

Get the name of structure as a string.

Returns:
The name of the structure.

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

Checks if the structure has the given name.

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

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:
name The new name of the structure.

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.

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

Get the value of the field with name fieldname.

Parameters:
fieldname the name of the field to get
value the Value class in which to store the value

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

Sets the field with the given name field to value.

If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. Returns this Gst::Structure for continued setting convenience. Please note that when setting special GStreamer fields such as Glib::Value<Gst::IntRange> and Glib::Value<Gst::Fraction> (using classes in value.h) they are converted to the GStreamer GTypes and thus when attempting to get these fields back, they can no longer be stored in the same Glib::Value<...>.

Parameters:
fieldname the name of the field to set
value the new value of the field
Returns:
this Gst::Structure

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

Removes the field with the given name.

If the field with the given name does not exist, the structure is unchanged. Returns this Gst::Structure for continued setting convenience.

Parameters:
fieldname the name of the field to remove
Returns:
this Gst::Structure

void Gst::Structure::remove_all_fields (  ) 

Removes all fields in a GstStructure.

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:
fieldname The name of the field.
Returns:
The Value of the field.

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. Also see map_in_place().

Parameters:
slot a slot to call for each field
Returns:
TRUE if the supplied slot returns TRUE For each of the fields, FALSE otherwise.

int Gst::Structure::size (  )  const

Get the number of fields in the structure.

Returns:
The number of fields in the structure.

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

Check if structure contains a field named fieldname.

Parameters:
fieldname The name of a field.
Returns:
true if the structure contains a field with the given name.

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:
fieldname The name of a field.
type The type of a value.
Returns:
true if the structure contains a field with the given name and type.

bool Gst::Structure::get_boolean ( const Glib::ustring &  fieldname,
Glib::ValueBase &  value 
) const

Sets the GValue of value to the boolean value of the given field.

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

Parameters:
fieldname the name of a field
value the Value class to set
Returns:
TRUE if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a boolean, this function returns FALSE.

bool Gst::Structure::get_int ( const Glib::ustring &  fieldname,
Glib::ValueBase &  value 
) const

Sets the GValue of value to the int value of the given field.

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

Parameters:
fieldname the name of a field
value the Value class to set
Returns:
TRUE if the value could be set correctly. If there was no field with fieldname or the existing field did not contain an int, this function returns FALSE returns FALSE

bool Gst::Structure::get_uint ( const Glib::ustring &  fieldname,
Glib::ValueBase &  value 
) const

Sets the GValue of value to the uint value of the given field.

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

Parameters:
fieldname the name of a field
value the Value class to set
Returns:
TRUE if the value could be set correctly. If there was no field with fieldname or the existing field did not contain an uint, this function returns FALSE returns FALSE

bool Gst::Structure::get_fourcc ( const Glib::ustring &  fieldname,
Glib::ValueBase &  value 
) const

Sets the GValue of value to the fourc value of the given field.

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

Parameters:
fieldname the name of a field
value the Value class to set
Returns:
TRUE if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a fourc, this function returns FALSE returns FALSE

bool Gst::Structure::get_double ( const Glib::ustring &  fieldname,
Glib::ValueBase &  value 
) const

Sets the GValue of value to the double value of the given field.

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

Parameters:
fieldname the name of a field
value the Value class to set
Returns:
TRUE if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a double, this function returns FALSE returns FALSE

bool Gst::Structure::get_string ( const Glib::ustring &  fieldname,
Glib::ValueBase &  value 
) const

Sets the GValue of value to the string value of the given field.

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

Parameters:
fieldname the name of a field
value the Value class to set
Returns:
TRUE if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a string, this function returns FALSE returns FALSE

bool Gst::Structure::get_date ( const Glib::ustring &  fieldname,
Glib::Date &  value 
) const

Sets the GValue of value to the GDate value of the given field.

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

Parameters:
fieldname the name of a field
date the Glib::Date class to set
Returns:
TRUE if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a GDate, this function returns FALSE returns FALSE

bool Gst::Structure::get_clock_time ( const Glib::ustring &  fieldname,
Glib::ValueBase &  value 
) const

Sets the GValue of value to the Gst::ClockTime value of the given field.

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

Parameters:
fieldname the name of a field
value the Value class to set
Returns:
TRUE if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a Gst::ClockTime, this function returns FALSE returns FALSE

bool Gst::Structure::get_enum ( const Glib::ustring &  fieldname,
GType  enumtype,
Glib::ValueBase &  value 
) const

Sets the GValue of value to the enum value of the given field.

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

Parameters:
fieldname the name of a field
value the Value class to set
Returns:
TRUE if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a enum, this function returns FALSE returns FALSE

bool Gst::Structure::get_fraction ( const Glib::ustring &  fieldname,
Gst::Fraction fraction 
) const

Sets the GValue of value to the Gst::Fraction value of the given field.

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

Parameters:
fieldname the name of a field
fraction the Gst::Fraction class to set
Returns:
TRUE if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a Gst::Fraction, this function returns FALSE returns FALSE

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:
slot a slot to call for each field
Returns:
TRUE if the supplied slot returns TRUE For each of the fields, FALSE otherwise.

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

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

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

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

Converts structure to a human-readable string representation.

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

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


Friends And Related Function Documentation

void swap ( Structure lhs,
Structure rhs 
) [related]

Parameters:
lhs The left-hand side
rhs The right-hand side

References swap().

Gst::Structure wrap ( GstStructure *  object,
bool  take_copy = false,
bool  destroy = true 
) [related]

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

Parameters:
object The C instance.
take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
destroy False if the result should not delete the C instance when wrapper is destroyed. True if it should.
Returns:
A C++ instance that wraps this C instance.


Member Data Documentation

GstStructure* Gst::Structure::gobject_ [protected]

Referenced by gobj().


The documentation for this class was generated from the following file:

Generated on Mon Jun 2 01:59:23 2008 for gstreamermm by  doxygen 1.5.5