GstChildProxy: GStreamer 1.0 Core Reference Manual

## GstChildProxy GstChildProxy — Interface for multi child elements. |

## Functions

guint | gst_child_proxy_get_children_count ()
GObject * | gst_child_proxy_get_child_by_name ()
GObject * | gst_child_proxy_get_child_by_index ()
gboolean | gst_child_proxy_lookup ()
void | gst_child_proxy_get_property ()
void | gst_child_proxy_get_valist ()
void | gst_child_proxy_get ()
void | gst_child_proxy_set_property ()
void | gst_child_proxy_set_valist ()
void | gst_child_proxy_set ()
void | gst_child_proxy_child_added ()
void | gst_child_proxy_child_removed ()

## Signals

void | child-added | Run First
void | child-removed | Run First

## Types and Values

| GstChildProxy
struct | GstChildProxyInterface

## Object Hierarchy

        GInterface
        ╰── GstChildProxy

## Prerequisites

GstChildProxy requires GObject.

## Known Implementations

GstChildProxy is implemented by GstBin and GstPipeline.

## Includes

    #include <gst/gst.h>

## Description

This interface abstracts handling of property sets for elements with children. Imagine elements such as mixers or polyphonic generators. They all have multiple GstPad or some kind of voice objects. Another use case are container elements like GstBin. The element implementing the interface acts as a parent for those child objects.

By implementing this interface the child properties can be accessed from the parent element by using `gst_child_proxy_get()` and `gst_child_proxy_set()`.

Property names are written as "child-name::property-name". The whole naming scheme is recursive. Thus "child1::child2::property" is valid too, if "child1" and "child2" implement the GstChildProxy interface.

## Functions

### gst_child_proxy_get_children_count ()

    guint
    gst_child_proxy_get_children_count (GstChildProxy *parent);

Gets the number of child objects this parent contains.

#### Parameters

parent | the parent object |

#### Returns

the number of child objects

MT safe.

### gst_child_proxy_get_child_by_name ()

    GObject *
    gst_child_proxy_get_child_by_name (GstChildProxy *parent,
                                       const gchar *name);

Looks up a child element by the given name.

This virtual method has a default implementation that uses GstObject together with `gst_object_get_name()`. If the interface is to be used with GObjects, this methods needs to be overridden.

#### Parameters

parent | the parent object to get the child from |
name | the child's name |

#### Returns

the child object or `NULL` if not found. Unref after usage.

MT safe.

[transfer full][nullable]

### gst_child_proxy_get_child_by_index ()

    GObject *
    gst_child_proxy_get_child_by_index (GstChildProxy *parent,
                                        guint index);

Fetches a child by its number.

#### Parameters

parent | the parent object to get the child from |
index | the child's position in the child list |

#### Returns

the child object or `NULL` if not found (index too high). Unref after usage.

MT safe.

[transfer full][nullable]

### gst_child_proxy_lookup ()

    gboolean
    gst_child_proxy_lookup (GstChildProxy *object,
                            const gchar *name,
                            GObject **target,
                            GParamSpec **pspec);

Looks up which object and GParamSpec would be effected by the given `name` .

MT safe.

#### Parameters

object | child proxy object to lookup the property in |
name | name of the property to look up |
target | pointer to a GObject that takes the real object to set property on. | [out][allow-none][transfer full]
pspec | pointer to take the GParamSpec describing the property. | [out][allow-none][transfer none]

#### Returns

`TRUE` if `target` and `pspec` could be found. `FALSE` otherwise. In that case the values for `pspec` and `target` are not modified. Unref `target` after usage. For plain GObjects `target` is the same as `object` .

### gst_child_proxy_get_property ()

    void
    gst_child_proxy_get_property (GstChildProxy *object,
                                  const gchar *name,
                                  GValue *value);

Gets a single property using the GstChildProxy mechanism. You are responsible for freeing it by calling `g_value_unset()`

#### Parameters

object | object to query |
name | name of the property |
value | a GValue that should take the result. | [out caller-allocates]

### gst_child_proxy_get_valist ()

    void
    gst_child_proxy_get_valist (GstChildProxy *object,
                                const gchar *first_property_name,
                                va_list var_args);

Gets properties of the parent object and its children.

#### Parameters

object | the object to query |
first_property_name | name of the first property to get |
var_args | return location for the first property, followed optionally by more name/return location pairs, followed by `NULL` |

### gst_child_proxy_get ()

    void
    gst_child_proxy_get (GstChildProxy *object,
                         const gchar *first_property_name,
                         ...);

Gets properties of the parent object and its children.

#### Parameters

object | the parent object |
first_property_name | name of the first property to get |
... | return location for the first property, followed optionally by more name/return location pairs, followed by `NULL` |

### gst_child_proxy_set_property ()

    void
    gst_child_proxy_set_property (GstChildProxy *object,
                                  const gchar *name,
                                  const GValue *value);

Sets a single property using the GstChildProxy mechanism.

#### Parameters

object | the parent object |
name | name of the property to set |
value | new GValue for the property |

### gst_child_proxy_set_valist ()

    void
    gst_child_proxy_set_valist (GstChildProxy *object,
                                const gchar *first_property_name,
                                va_list var_args);

Sets properties of the parent object and its children.

#### Parameters

object | the parent object |
first_property_name | name of the first property to set |
var_args | value for the first property, followed optionally by more name/value pairs, followed by `NULL` |

### gst_child_proxy_set ()

    void
    gst_child_proxy_set (GstChildProxy *object,
                         const gchar *first_property_name,
                         ...);

Sets properties of the parent object and its children.

#### Parameters

object | the parent object |
first_property_name | name of the first property to set |
... | value for the first property, followed optionally by more name/value pairs, followed by `NULL` |

### gst_child_proxy_child_added ()

    void
    gst_child_proxy_child_added (GstChildProxy *parent,
                                 GObject *child,
                                 const gchar *name);

Emits the "child-added" signal.

#### Parameters

parent | the parent object |
child | the newly added child |
name | the name of the new child |

### gst_child_proxy_child_removed ()

    void
    gst_child_proxy_child_removed (GstChildProxy *parent,
                                   GObject *child,
                                   const gchar *name);

Emits the "child-removed" signal.

#### Parameters

parent | the parent object |
child | the removed child |
name | the name of the old child |

## Types and Values

### GstChildProxy

    typedef struct _GstChildProxy GstChildProxy;

Opaque GstChildProxy data structure.

### struct GstChildProxyInterface

    struct GstChildProxyInterface {
      GTypeInterface parent;

      /* methods */
      GObject * (*get_child_by_name)  (GstChildProxy * parent, const gchar * name);
      GObject * (*get_child_by_index) (GstChildProxy * parent, guint index);
      guint     (*get_children_count) (GstChildProxy * parent);
    };

GstChildProxy interface.

#### Members

GTypeInterface `parent`; | parent interface type. |
`get_child_by_name` () | virtual method to fetch the child by name |
`get_child_by_index` () | virtual method to fetch the child by index |
`get_children_count` () | virtual method to get the children count |

## Signal Details

### The `“child-added”` signal

    void
    user_function (GstChildProxy *child_proxy,
                   GObject       *object,
                   gchar         *name,
                   gpointer       user_data)

Will be emitted after the `object` was added to the `child_proxy` .

#### Parameters

child_proxy | the GstChildProxy |
object | the GObject that was added |
name | the name of the new child |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“child-removed”` signal

    void
    user_function (GstChildProxy *child_proxy,
                   GObject       *object,
                   gchar         *name,
                   gpointer       user_data)

Will be emitted after the `object` was removed from the `child_proxy` .

#### Parameters

child_proxy | the GstChildProxy |
object | the GObject that was removed |
name | the name of the old child |
user_data | user data set when the signal handler was connected. |

Flags: Run First

## See Also

GstBin