2 * Copyright (C) 2012 Olivier Crete <olivier.crete@collabora.com>
4 * gstdeviceprovider.c: Device probing and monitoring
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:gstdeviceprovider
24 * @title: GstDeviceProvider
25 * @short_description: A device provider
26 * @see_also: #GstDevice, #GstDeviceMonitor
28 * A #GstDeviceProvider subclass is provided by a plugin that handles devices
29 * if there is a way to programatically list connected devices. It can also
30 * optionally provide updates to the list of connected devices.
32 * Each #GstDeviceProvider subclass is a singleton, a plugin should
33 * normally provide a single subclass for all devices.
35 * Applications would normally use a #GstDeviceMonitor to monitor devices
36 * from all relevant providers.
45 #include "gst_private.h"
47 #include "gstdeviceprovider.h"
49 #include "gstelementmetadata.h"
52 struct _GstDeviceProviderPrivate
58 gboolean started_count;
60 GList *hidden_providers;
70 static guint gst_device_provider_signals[LAST_SIGNAL] = { 0 };
72 /* this is used in gstelementfactory.c:gst_element_register() */
73 GQuark __gst_deviceproviderclass_factory = 0;
75 static void gst_device_provider_class_init (GstDeviceProviderClass * klass);
76 static void gst_device_provider_init (GstDeviceProvider * element);
77 static void gst_device_provider_base_class_init (gpointer g_class);
78 static void gst_device_provider_dispose (GObject * object);
79 static void gst_device_provider_finalize (GObject * object);
81 static gpointer gst_device_provider_parent_class = NULL;
84 gst_device_provider_get_type (void)
86 static volatile gsize gst_device_provider_type = 0;
88 if (g_once_init_enter (&gst_device_provider_type)) {
90 static const GTypeInfo element_info = {
91 sizeof (GstDeviceProviderClass),
92 gst_device_provider_base_class_init,
93 NULL, /* base_class_finalize */
94 (GClassInitFunc) gst_device_provider_class_init,
97 sizeof (GstDeviceProvider),
99 (GInstanceInitFunc) gst_device_provider_init,
103 _type = g_type_register_static (GST_TYPE_OBJECT, "GstDeviceProvider",
104 &element_info, G_TYPE_FLAG_ABSTRACT);
106 __gst_deviceproviderclass_factory =
107 g_quark_from_static_string ("GST_DEVICEPROVIDERCLASS_FACTORY");
108 g_once_init_leave (&gst_device_provider_type, _type);
110 return gst_device_provider_type;
114 gst_device_provider_base_class_init (gpointer g_class)
116 GstDeviceProviderClass *klass = GST_DEVICE_PROVIDER_CLASS (g_class);
118 /* Copy the element details here so elements can inherit the
119 * details from their base class and classes only need to set
120 * the details in class_init instead of base_init */
122 klass->metadata ? gst_structure_copy (klass->metadata) :
123 gst_structure_new_empty ("metadata");
125 klass->factory = g_type_get_qdata (G_TYPE_FROM_CLASS (klass),
126 __gst_deviceproviderclass_factory);
130 gst_device_provider_class_init (GstDeviceProviderClass * klass)
132 GObjectClass *gobject_class = (GObjectClass *) klass;
134 gst_device_provider_parent_class = g_type_class_peek_parent (klass);
136 g_type_class_add_private (klass, sizeof (GstDeviceProviderPrivate));
138 gobject_class->dispose = gst_device_provider_dispose;
139 gobject_class->finalize = gst_device_provider_finalize;
141 gst_device_provider_signals[PROVIDER_HIDDEN] =
142 g_signal_new ("provider-hidden", G_TYPE_FROM_CLASS (klass),
143 G_SIGNAL_RUN_FIRST, 0, NULL,
144 NULL, g_cclosure_marshal_generic, G_TYPE_NONE, 1, G_TYPE_STRING);
146 gst_device_provider_signals[PROVIDER_UNHIDDEN] =
147 g_signal_new ("provider-unhidden", G_TYPE_FROM_CLASS (klass),
148 G_SIGNAL_RUN_FIRST, 0, NULL,
149 NULL, g_cclosure_marshal_generic, G_TYPE_NONE, 1, G_TYPE_STRING);
153 gst_device_provider_init (GstDeviceProvider * provider)
155 provider->priv = G_TYPE_INSTANCE_GET_PRIVATE (provider,
156 GST_TYPE_DEVICE_PROVIDER, GstDeviceProviderPrivate);
158 g_mutex_init (&provider->priv->start_lock);
160 provider->priv->bus = gst_bus_new ();
161 gst_bus_set_flushing (provider->priv->bus, TRUE);
166 gst_device_provider_dispose (GObject * object)
168 GstDeviceProvider *provider = GST_DEVICE_PROVIDER (object);
170 gst_object_replace ((GstObject **) & provider->priv->bus, NULL);
172 GST_OBJECT_LOCK (provider);
173 g_list_free_full (provider->devices, (GDestroyNotify) gst_object_unparent);
174 provider->devices = NULL;
175 GST_OBJECT_UNLOCK (provider);
177 G_OBJECT_CLASS (gst_device_provider_parent_class)->dispose (object);
181 gst_device_provider_finalize (GObject * object)
183 GstDeviceProvider *provider = GST_DEVICE_PROVIDER (object);
185 g_mutex_clear (&provider->priv->start_lock);
187 G_OBJECT_CLASS (gst_device_provider_parent_class)->finalize (object);
191 * gst_device_provider_class_add_metadata:
192 * @klass: class to set metadata for
193 * @key: the key to set
194 * @value: the value to set
196 * Set @key with @value as metadata in @klass.
201 gst_device_provider_class_add_metadata (GstDeviceProviderClass * klass,
202 const gchar * key, const gchar * value)
204 g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
205 g_return_if_fail (key != NULL);
206 g_return_if_fail (value != NULL);
208 gst_structure_set ((GstStructure *) klass->metadata,
209 key, G_TYPE_STRING, value, NULL);
213 * gst_device_provider_class_add_static_metadata:
214 * @klass: class to set metadata for
215 * @key: the key to set
216 * @value: (transfer full): the value to set
218 * Set @key with @value as metadata in @klass.
220 * Same as gst_device_provider_class_add_metadata(), but @value must be a static string
221 * or an inlined string, as it will not be copied. (GStreamer plugins will
222 * be made resident once loaded, so this function can be used even from
223 * dynamically loaded plugins.)
228 gst_device_provider_class_add_static_metadata (GstDeviceProviderClass * klass,
229 const gchar * key, const gchar * value)
231 GValue val = G_VALUE_INIT;
233 g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
234 g_return_if_fail (key != NULL);
235 g_return_if_fail (value != NULL);
237 g_value_init (&val, G_TYPE_STRING);
238 g_value_set_static_string (&val, value);
239 gst_structure_take_value ((GstStructure *) klass->metadata, key, &val);
243 * gst_device_provider_class_set_metadata:
244 * @klass: class to set metadata for
245 * @longname: The long English name of the device provider. E.g. "File Sink"
246 * @classification: String describing the type of device provider, as an
247 * unordered list separated with slashes ('/'). See draft-klass.txt of the
249 * for more details and common types. E.g: "Sink/File"
250 * @description: Sentence describing the purpose of the device provider.
251 * E.g: "Write stream to a file"
252 * @author: Name and contact details of the author(s). Use \n to separate
253 * multiple author metadata. E.g: "Joe Bloggs <joe.blogs at foo.com>"
255 * Sets the detailed information for a #GstDeviceProviderClass.
257 * > This function is for use in _class_init functions only.
262 gst_device_provider_class_set_metadata (GstDeviceProviderClass * klass,
263 const gchar * longname, const gchar * classification,
264 const gchar * description, const gchar * author)
266 g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
267 g_return_if_fail (longname != NULL && *longname != '\0');
268 g_return_if_fail (classification != NULL && *classification != '\0');
269 g_return_if_fail (description != NULL && *description != '\0');
270 g_return_if_fail (author != NULL && *author != '\0');
272 gst_structure_id_set ((GstStructure *) klass->metadata,
273 GST_QUARK (ELEMENT_METADATA_LONGNAME), G_TYPE_STRING, longname,
274 GST_QUARK (ELEMENT_METADATA_KLASS), G_TYPE_STRING, classification,
275 GST_QUARK (ELEMENT_METADATA_DESCRIPTION), G_TYPE_STRING, description,
276 GST_QUARK (ELEMENT_METADATA_AUTHOR), G_TYPE_STRING, author, NULL);
280 * gst_device_provider_class_set_static_metadata:
281 * @klass: class to set metadata for
282 * @longname: (transfer full): The long English name of the element. E.g. "File Sink"
283 * @classification: (transfer full): String describing the type of element, as
284 * an unordered list separated with slashes ('/'). See draft-klass.txt of the
285 * design docs for more details and common types. E.g: "Sink/File"
286 * @description: (transfer full): Sentence describing the purpose of the
287 * element. E.g: "Write stream to a file"
288 * @author: (transfer full): Name and contact details of the author(s). Use \n
289 * to separate multiple author metadata. E.g: "Joe Bloggs <joe.blogs at
292 * Sets the detailed information for a #GstDeviceProviderClass.
294 * > This function is for use in _class_init functions only.
296 * Same as gst_device_provider_class_set_metadata(), but @longname, @classification,
297 * @description, and @author must be static strings or inlined strings, as
298 * they will not be copied. (GStreamer plugins will be made resident once
299 * loaded, so this function can be used even from dynamically loaded plugins.)
304 gst_device_provider_class_set_static_metadata (GstDeviceProviderClass * klass,
305 const gchar * longname, const gchar * classification,
306 const gchar * description, const gchar * author)
308 GstStructure *s = (GstStructure *) klass->metadata;
309 GValue val = G_VALUE_INIT;
311 g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
312 g_return_if_fail (longname != NULL && *longname != '\0');
313 g_return_if_fail (classification != NULL && *classification != '\0');
314 g_return_if_fail (description != NULL && *description != '\0');
315 g_return_if_fail (author != NULL && *author != '\0');
317 g_value_init (&val, G_TYPE_STRING);
319 g_value_set_static_string (&val, longname);
320 gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_LONGNAME), &val);
322 g_value_set_static_string (&val, classification);
323 gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_KLASS), &val);
325 g_value_set_static_string (&val, description);
326 gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_DESCRIPTION),
329 g_value_set_static_string (&val, author);
330 gst_structure_id_take_value (s, GST_QUARK (ELEMENT_METADATA_AUTHOR), &val);
334 * gst_device_provider_class_get_metadata:
335 * @klass: class to get metadata for
336 * @key: the key to get
338 * Get metadata with @key in @klass.
340 * Returns: (nullable): the metadata for @key.
345 gst_device_provider_class_get_metadata (GstDeviceProviderClass * klass,
348 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass), NULL);
349 g_return_val_if_fail (key != NULL, NULL);
351 return gst_structure_get_string ((GstStructure *) klass->metadata, key);
355 * gst_device_provider_get_metadata:
356 * @provider: provider to get metadata for
357 * @key: the key to get
359 * Get metadata with @key in @provider.
361 * Returns: the metadata for @key.
366 gst_device_provider_get_metadata (GstDeviceProvider * provider,
369 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
370 g_return_val_if_fail (key != NULL, NULL);
373 gst_device_provider_class_get_metadata (GST_DEVICE_PROVIDER_GET_CLASS
378 * gst_device_provider_get_devices:
379 * @provider: A #GstDeviceProvider
381 * Gets a list of devices that this provider understands. This may actually
382 * probe the hardware if the provider is not currently started.
384 * Returns: (transfer full) (element-type GstDevice): a #GList of
391 gst_device_provider_get_devices (GstDeviceProvider * provider)
393 GstDeviceProviderClass *klass;
394 GList *devices = NULL;
398 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
399 klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
401 g_mutex_lock (&provider->priv->start_lock);
402 started = (provider->priv->started_count > 0);
405 GST_OBJECT_LOCK (provider);
406 for (item = provider->devices; item; item = item->next)
407 devices = g_list_prepend (devices, gst_object_ref (item->data));
408 GST_OBJECT_UNLOCK (provider);
409 } else if (klass->probe)
410 devices = klass->probe (provider);
412 g_mutex_unlock (&provider->priv->start_lock);
418 * gst_device_provider_start:
419 * @provider: A #GstDeviceProvider
421 * Starts providering the devices. This will cause #GST_MESSAGE_DEVICE_ADDED
422 * and #GST_MESSAGE_DEVICE_REMOVED messages to be posted on the provider's bus
423 * when devices are added or removed from the system.
425 * Since the #GstDeviceProvider is a singleton,
426 * gst_device_provider_start() may already have been called by another
427 * user of the object, gst_device_provider_stop() needs to be called the same
430 * Returns: %TRUE if the device providering could be started
436 gst_device_provider_start (GstDeviceProvider * provider)
438 GstDeviceProviderClass *klass;
439 gboolean ret = FALSE;
441 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), FALSE);
442 klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
444 g_mutex_lock (&provider->priv->start_lock);
446 if (provider->priv->started_count > 0) {
452 ret = klass->start (provider);
455 provider->priv->started_count++;
456 gst_bus_set_flushing (provider->priv->bus, FALSE);
461 g_mutex_unlock (&provider->priv->start_lock);
467 * gst_device_provider_stop:
468 * @provider: A #GstDeviceProvider
470 * Decreases the use-count by one. If the use count reaches zero, this
471 * #GstDeviceProvider will stop providering the devices. This needs to be
472 * called the same number of times that gst_device_provider_start() was called.
478 gst_device_provider_stop (GstDeviceProvider * provider)
480 GstDeviceProviderClass *klass;
482 g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
483 klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
485 g_mutex_lock (&provider->priv->start_lock);
487 if (provider->priv->started_count == 1) {
488 gst_bus_set_flushing (provider->priv->bus, TRUE);
490 klass->stop (provider);
491 GST_OBJECT_LOCK (provider);
492 g_list_free_full (provider->devices, (GDestroyNotify) gst_object_unparent);
493 provider->devices = NULL;
494 GST_OBJECT_UNLOCK (provider);
495 } else if (provider->priv->started_count < 1) {
497 ("Trying to stop a GstDeviceProvider %s which is already stopped",
498 GST_OBJECT_NAME (provider));
501 provider->priv->started_count--;
502 g_mutex_unlock (&provider->priv->start_lock);
507 * gst_device_provider_get_factory:
508 * @provider: a #GstDeviceProvider to request the device provider factory of.
510 * Retrieves the factory that was used to create this device provider.
512 * Returns: (transfer none): the #GstDeviceProviderFactory used for
513 * creating this device provider. no refcounting is needed.
517 GstDeviceProviderFactory *
518 gst_device_provider_get_factory (GstDeviceProvider * provider)
520 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
522 return GST_DEVICE_PROVIDER_GET_CLASS (provider)->factory;
526 * gst_device_provider_can_provider:
527 * @provider: a #GstDeviceProvider
529 * If this function returns %TRUE, then the device provider can provider if
530 * devices are added or removed. Otherwise, it can only do static probing.
532 * Returns: %TRUE if the #GstDeviceProvider support providering, %FALSE otherwise
535 gst_device_provider_can_monitor (GstDeviceProvider * provider)
537 GstDeviceProviderClass *klass;
539 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), FALSE);
540 klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
549 * gst_device_provider_get_bus:
550 * @provider: a #GstDeviceProvider
552 * Gets the #GstBus of this #GstDeviceProvider
554 * Returns: (transfer full): a #GstBus
559 gst_device_provider_get_bus (GstDeviceProvider * provider)
561 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
563 return gst_object_ref (provider->priv->bus);
567 * gst_device_provider_device_add:
568 * @provider: a #GstDeviceProvider
569 * @device: (transfer floating): a #GstDevice that has been added
571 * Posts a message on the provider's #GstBus to inform applications that
572 * a new device has been added.
574 * This is for use by subclasses.
576 * @device's reference count will be incremented, and any floating reference
577 * will be removed (see gst_object_ref_sink()).
582 gst_device_provider_device_add (GstDeviceProvider * provider,
587 g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
588 g_return_if_fail (GST_IS_DEVICE (device));
590 if (!gst_object_set_parent (GST_OBJECT (device), GST_OBJECT (provider))) {
591 GST_WARNING_OBJECT (provider, "Could not parent device %p to provider,"
592 " it already has a parent", device);
596 GST_OBJECT_LOCK (provider);
597 /* Take an additional reference so we can be sure nobody removed it from the
598 * provider in the meantime and we can safely emit the message */
599 gst_object_ref (device);
600 provider->devices = g_list_prepend (provider->devices, device);
601 GST_OBJECT_UNLOCK (provider);
603 message = gst_message_new_device_added (GST_OBJECT (provider), device);
604 gst_bus_post (provider->priv->bus, message);
605 gst_object_unref (device);
610 * gst_device_provider_device_remove:
611 * @provider: a #GstDeviceProvider
612 * @device: a #GstDevice that has been removed
614 * Posts a message on the provider's #GstBus to inform applications that
615 * a device has been removed.
617 * This is for use by subclasses.
622 gst_device_provider_device_remove (GstDeviceProvider * provider,
628 g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
629 g_return_if_fail (GST_IS_DEVICE (device));
631 GST_OBJECT_LOCK (provider);
632 item = g_list_find (provider->devices, device);
634 provider->devices = g_list_delete_link (provider->devices, item);
636 GST_OBJECT_UNLOCK (provider);
638 message = gst_message_new_device_removed (GST_OBJECT (provider), device);
639 g_signal_emit_by_name (device, "removed");
640 gst_bus_post (provider->priv->bus, message);
642 gst_object_unparent (GST_OBJECT (device));
646 * gst_device_provider_get_hidden_providers:
647 * @provider: a #GstDeviceProvider
649 * Get the provider factory names of the #GstDeviceProvider instances that
650 * are hidden by @provider.
652 * Returns: (transfer full) (array zero-terminated=1) (element-type gchar*):
653 * a list of hidden providers factory names or %NULL when
654 * nothing is hidden by @provider. Free with g_strfreev.
659 gst_device_provider_get_hidden_providers (GstDeviceProvider * provider)
665 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
667 GST_OBJECT_LOCK (provider);
668 len = g_list_length (provider->priv->hidden_providers);
672 res = g_new (gchar *, len + 1);
673 for (i = 0, walk = provider->priv->hidden_providers; walk;
674 walk = g_list_next (walk), i++)
675 res[i] = g_strdup (walk->data);
679 GST_OBJECT_UNLOCK (provider);
685 * gst_device_provider_hide_provider:
686 * @provider: a #GstDeviceProvider
687 * @name: a provider factory name
689 * Make @provider hide the devices from the factory with @name.
691 * This function is used when @provider will also provide the devices reported
692 * by provider factory @name. A monitor should stop monitoring the
693 * device provider with @name to avoid duplicate devices.
698 gst_device_provider_hide_provider (GstDeviceProvider * provider,
702 const gchar *hidden_name = NULL;
704 g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
705 g_return_if_fail (name != NULL);
707 GST_OBJECT_LOCK (provider);
709 g_list_find_custom (provider->priv->hidden_providers, name,
710 (GCompareFunc) g_strcmp0);
713 provider->priv->hidden_providers =
714 g_list_prepend (provider->priv->hidden_providers, g_strdup (name));
716 GST_OBJECT_UNLOCK (provider);
719 g_signal_emit (provider, gst_device_provider_signals[PROVIDER_HIDDEN],
724 * gst_device_provider_unhide_provider:
725 * @provider: a #GstDeviceProvider
726 * @name: a provider factory name
728 * Make @provider unhide the devices from factory @name.
730 * This function is used when @provider will no longer provide the devices
731 * reported by provider factory @name. A monitor should start
732 * monitoring the devices from provider factory @name in order to see
738 gst_device_provider_unhide_provider (GstDeviceProvider * provider,
742 gchar *unhidden_name = NULL;
744 g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
745 g_return_if_fail (name != NULL);
747 GST_OBJECT_LOCK (provider);
749 g_list_find_custom (provider->priv->hidden_providers, name,
750 (GCompareFunc) g_strcmp0);
752 unhidden_name = find->data;
753 provider->priv->hidden_providers =
754 g_list_delete_link (provider->priv->hidden_providers, find);
756 GST_OBJECT_UNLOCK (provider);
759 g_signal_emit (provider,
760 gst_device_provider_signals[PROVIDER_UNHIDDEN], 0, unhidden_name);
761 g_free (unhidden_name);