2 * Copyright (C) 2005 Stefan Kost <ensonic@users.sf.net>
4 * gstchildproxy.c: interface for multi child elements
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
23 * SECTION:gstchildproxy
24 * @short_description: Interface for multi child elements.
27 * This interface abstracts handling of property sets for elements with
28 * children. Imagine elements such as mixers or polyphonic generators. They all
29 * have multiple #GstPad or some kind of voice objects. Another use case are
30 * container elements like #GstBin.
31 * The element implementing the interface acts as a parent for those child
34 * By implementing this interface the child properties can be accessed from the
35 * parent element by using gst_child_proxy_get() and gst_child_proxy_set().
37 * Property names are written as "child-name::property-name". The whole naming
38 * scheme is recursive. Thus "child1::child2::property" is valid too, if
39 * "child1" and "child2" implement the #GstChildProxy interface.
42 #include "gst_private.h"
44 #include "gstchildproxy.h"
45 #include <gobject/gvaluecollector.h>
55 static guint signals[LAST_SIGNAL] = { 0 };
58 gst_child_proxy_default_get_child_by_name (GstChildProxy * parent,
62 GObject *object, *result;
65 g_return_val_if_fail (GST_IS_CHILD_PROXY (parent), NULL);
66 g_return_val_if_fail (name != NULL, NULL);
70 count = gst_child_proxy_get_children_count (parent);
71 for (i = 0; i < count; i++) {
74 if (!(object = gst_child_proxy_get_child_by_index (parent, i)))
77 if (!GST_IS_OBJECT (object)) {
80 object_name = gst_object_get_name (GST_OBJECT_CAST (object));
81 if (object_name == NULL) {
82 g_warning ("child %u of parent %s has no name", i,
83 GST_OBJECT_NAME (parent));
86 eq = g_str_equal (object_name, name);
94 g_object_unref (object);
101 * gst_child_proxy_get_child_by_name:
102 * @parent: the parent object to get the child from
103 * @name: the childs name
105 * Looks up a child element by the given name.
107 * This virtual method has a default implementation that uses #GstObject
108 * together with gst_object_get_name(). If the interface is to be used with
109 * #GObjects, this methods needs to be overridden.
111 * Returns: (transfer full): the child object or %NULL if not found. Unref
117 gst_child_proxy_get_child_by_name (GstChildProxy * parent, const gchar * name)
119 g_return_val_if_fail (GST_IS_CHILD_PROXY (parent), 0);
121 return (GST_CHILD_PROXY_GET_INTERFACE (parent)->get_child_by_name (parent,
126 * gst_child_proxy_get_child_by_index:
127 * @parent: the parent object to get the child from
128 * @index: the childs position in the child list
130 * Fetches a child by its number.
132 * Returns: (transfer full): the child object or %NULL if not found (index
133 * too high). Unref after usage.
138 gst_child_proxy_get_child_by_index (GstChildProxy * parent, guint index)
140 g_return_val_if_fail (GST_IS_CHILD_PROXY (parent), NULL);
142 return (GST_CHILD_PROXY_GET_INTERFACE (parent)->get_child_by_index (parent,
147 * gst_child_proxy_get_children_count:
148 * @parent: the parent object
150 * Gets the number of child objects this parent contains.
152 * Returns: the number of child objects
157 gst_child_proxy_get_children_count (GstChildProxy * parent)
159 g_return_val_if_fail (GST_IS_CHILD_PROXY (parent), 0);
161 return (GST_CHILD_PROXY_GET_INTERFACE (parent)->get_children_count (parent));
165 * gst_child_proxy_lookup:
166 * @object: object to lookup the property in
167 * @name: name of the property to look up
168 * @target: (out) (allow-none) (transfer full): pointer to a #GObject that
169 * takes the real object to set property on
170 * @pspec: (out) (allow-none) (transfer none): pointer to take the #GParamSpec
171 * describing the property
173 * Looks up which object and #GParamSpec would be effected by the given @name.
177 * Returns: TRUE if @target and @pspec could be found. FALSE otherwise. In that
178 * case the values for @pspec and @target are not modified. Unref @target after
179 * usage. For plain GObjects @target is the same as @object.
182 gst_child_proxy_lookup (GObject * object, const gchar * name,
183 GObject ** target, GParamSpec ** pspec)
185 gboolean res = FALSE;
186 gchar **names, **current;
188 g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
189 g_return_val_if_fail (name != NULL, FALSE);
191 g_object_ref (object);
193 current = names = g_strsplit (name, "::", -1);
194 // find the owner of the property
198 if (!GST_IS_CHILD_PROXY (object)) {
200 ("object %s is not a parent, so you cannot request a child by name %s",
201 (GST_IS_OBJECT (object) ? GST_OBJECT_NAME (object) : ""), current[0]);
204 next = gst_child_proxy_get_child_by_name (GST_CHILD_PROXY (object),
207 GST_INFO ("no such object %s", current[0]);
210 g_object_unref (object);
216 if (current[1] == NULL) {
218 g_object_class_find_property (G_OBJECT_GET_CLASS (object), current[0]);
220 GST_INFO ("no param spec named %s", current[0]);
225 g_object_ref (object);
231 g_object_unref (object);
237 * gst_child_proxy_get_property:
238 * @object: object to query
239 * @name: name of the property
240 * @value: (out caller-allocates): a #GValue that should take the result.
242 * Gets a single property using the GstChildProxy mechanism.
243 * You are responsible for freeing it by calling g_value_unset()
246 gst_child_proxy_get_property (GstChildProxy * object, const gchar * name,
252 g_return_if_fail (GST_IS_CHILD_PROXY (object));
253 g_return_if_fail (name != NULL);
254 g_return_if_fail (G_IS_VALUE (value));
256 if (!gst_child_proxy_lookup ((GObject *) object, name, &target, &pspec))
259 g_object_get_property (target, pspec->name, value);
260 g_object_unref (target);
266 g_warning ("no property %s in object %s", name,
267 (GST_IS_OBJECT (object) ? GST_OBJECT_NAME (object) : ""));
273 * gst_child_proxy_get_valist:
274 * @object: the object to query
275 * @first_property_name: name of the first property to get
276 * @var_args: return location for the first property, followed optionally by more name/return location pairs, followed by NULL
278 * Gets properties of the parent object and its children.
281 gst_child_proxy_get_valist (GstChildProxy * object,
282 const gchar * first_property_name, va_list var_args)
286 GValue value = { 0, };
290 g_return_if_fail (GST_IS_CHILD_PROXY (object));
292 name = first_property_name;
294 /* iterate over pairs */
296 if (!gst_child_proxy_lookup ((GObject *) object, name, &target, &pspec))
299 g_value_init (&value, pspec->value_type);
300 g_object_get_property (target, pspec->name, &value);
301 g_object_unref (target);
303 G_VALUE_LCOPY (&value, var_args, 0, &error);
306 g_value_unset (&value);
307 name = va_arg (var_args, gchar *);
313 g_warning ("no property %s in object %s", name,
314 (GST_IS_OBJECT (object) ? GST_OBJECT_NAME (object) : ""));
319 g_warning ("error copying value %s in object %s: %s", pspec->name,
320 (GST_IS_OBJECT (object) ? GST_OBJECT_NAME (object) : ""), error);
321 g_value_unset (&value);
327 * gst_child_proxy_get:
328 * @object: the parent object
329 * @first_property_name: name of the first property to get
330 * @...: return location for the first property, followed optionally by more name/return location pairs, followed by NULL
332 * Gets properties of the parent object and its children.
335 gst_child_proxy_get (GstChildProxy * object, const gchar * first_property_name,
340 g_return_if_fail (GST_IS_CHILD_PROXY (object));
342 va_start (var_args, first_property_name);
343 gst_child_proxy_get_valist (object, first_property_name, var_args);
348 * gst_child_proxy_set_property:
349 * @object: the parent object
350 * @name: name of the property to set
351 * @value: new #GValue for the property
353 * Sets a single property using the GstChildProxy mechanism.
356 gst_child_proxy_set_property (GstChildProxy * object, const gchar * name,
357 const GValue * value)
362 g_return_if_fail (GST_IS_CHILD_PROXY (object));
363 g_return_if_fail (name != NULL);
364 g_return_if_fail (G_IS_VALUE (value));
366 if (!gst_child_proxy_lookup ((GObject *) object, name, &target, &pspec))
369 g_object_set_property (target, pspec->name, value);
370 g_object_unref (target);
375 g_warning ("cannot set property %s on object %s", name,
376 (GST_IS_OBJECT (object) ? GST_OBJECT_NAME (object) : ""));
382 * gst_child_proxy_set_valist:
383 * @object: the parent object
384 * @first_property_name: name of the first property to set
385 * @var_args: value for the first property, followed optionally by more name/value pairs, followed by NULL
387 * Sets properties of the parent object and its children.
390 gst_child_proxy_set_valist (GstChildProxy * object,
391 const gchar * first_property_name, va_list var_args)
395 GValue value = { 0, };
399 g_return_if_fail (GST_IS_CHILD_PROXY (object));
401 name = first_property_name;
403 /* iterate over pairs */
405 if (!gst_child_proxy_lookup ((GObject *) object, name, &target, &pspec))
408 G_VALUE_COLLECT_INIT (&value, pspec->value_type, var_args,
409 G_VALUE_NOCOPY_CONTENTS, &error);
414 g_object_set_property (target, pspec->name, &value);
415 g_object_unref (target);
417 g_value_unset (&value);
418 name = va_arg (var_args, gchar *);
424 g_warning ("no property %s in object %s", name,
425 (GST_IS_OBJECT (object) ? GST_OBJECT_NAME (object) : ""));
430 g_warning ("error copying value %s in object %s: %s", pspec->name,
431 (GST_IS_OBJECT (object) ? GST_OBJECT_NAME (object) : ""), error);
432 g_value_unset (&value);
433 g_object_unref (target);
439 * gst_child_proxy_set:
440 * @object: the parent object
441 * @first_property_name: name of the first property to set
442 * @...: value for the first property, followed optionally by more name/value pairs, followed by NULL
444 * Sets properties of the parent object and its children.
447 gst_child_proxy_set (GstChildProxy * object, const gchar * first_property_name,
452 g_return_if_fail (GST_IS_CHILD_PROXY (object));
454 va_start (var_args, first_property_name);
455 gst_child_proxy_set_valist (object, first_property_name, var_args);
460 * gst_child_proxy_child_added:
461 * @parent: the parent object
462 * @child: the newly added child
463 * @name: the name of the new child
465 * Emits the "child-added" signal.
468 gst_child_proxy_child_added (GstChildProxy * parent, GObject * child,
471 g_signal_emit (parent, signals[CHILD_ADDED], 0, child, name);
475 * gst_child_proxy_child_removed:
476 * @parent: the parent object
477 * @child: the removed child
478 * @name: the name of the old child
480 * Emits the "child-removed" signal.
483 gst_child_proxy_child_removed (GstChildProxy * parent, GObject * child,
486 g_signal_emit (parent, signals[CHILD_REMOVED], 0, child, name);
489 /* gobject methods */
492 gst_child_proxy_class_init (gpointer g_class, gpointer class_data)
494 GstChildProxyInterface *iface = (GstChildProxyInterface *) g_class;
496 iface->get_child_by_name = gst_child_proxy_default_get_child_by_name;
500 gst_child_proxy_base_init (gpointer g_class)
502 static gboolean initialized = FALSE;
505 /* create interface signals and properties here. */
507 * GstChildProxy::child-added:
508 * @child_proxy: the #GstChildProxy
509 * @object: the #GObject that was added
510 * @name: the name of the new child
512 * Will be emitted after the @object was added to the @child_proxy.
514 signals[CHILD_ADDED] =
515 g_signal_new ("child-added", G_TYPE_FROM_CLASS (g_class),
516 G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GstChildProxyInterface,
517 child_added), NULL, NULL, g_cclosure_marshal_generic, G_TYPE_NONE,
518 2, G_TYPE_OBJECT, G_TYPE_STRING);
521 * GstChildProxy::child-removed:
522 * @child_proxy: the #GstChildProxy
523 * @object: the #GObject that was removed
524 * @name: the name of the old child
526 * Will be emitted after the @object was removed from the @child_proxy.
528 signals[CHILD_REMOVED] =
529 g_signal_new ("child-removed", G_TYPE_FROM_CLASS (g_class),
530 G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GstChildProxyInterface,
531 child_removed), NULL, NULL, g_cclosure_marshal_generic, G_TYPE_NONE,
532 2, G_TYPE_OBJECT, G_TYPE_STRING);
539 gst_child_proxy_get_type (void)
541 static volatile gsize type = 0;
543 if (g_once_init_enter (&type)) {
545 static const GTypeInfo info = {
546 sizeof (GstChildProxyInterface),
547 gst_child_proxy_base_init, /* base_init */
548 NULL, /* base_finalize */
549 gst_child_proxy_class_init, /* class_init */
550 NULL, /* class_finalize */
551 NULL, /* class_data */
554 NULL /* instance_init */
558 g_type_register_static (G_TYPE_INTERFACE, "GstChildProxy", &info, 0);
560 g_type_interface_add_prerequisite (_type, G_TYPE_OBJECT);
561 g_once_init_leave (&type, (gsize) _type);