2 * Copyright (C) 2013 Olivier Crete <olivier.crete@collabora.com>
4 * gstdevicemonitor.c: device monitor
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:gstdevicemonitor
24 * @title: GstDeviceMonitor
25 * @short_description: A device monitor and prober
26 * @see_also: #GstDevice, #GstDeviceProvider
28 * Applications should create a #GstDeviceMonitor when they want
29 * to probe, list and monitor devices of a specific type. The
30 * #GstDeviceMonitor will create the appropriate
31 * #GstDeviceProvider objects and manage them. It will then post
32 * messages on its #GstBus for devices that have been added and
35 * The device monitor will monitor all devices matching the filters that
36 * the application has set.
38 * The basic use pattern of a device monitor is as follows:
41 * my_bus_func (GstBus * bus, GstMessage * message, gpointer user_data)
46 * switch (GST_MESSAGE_TYPE (message)) {
47 * case GST_MESSAGE_DEVICE_ADDED:
48 * gst_message_parse_device_added (message, &device);
49 * name = gst_device_get_display_name (device);
50 * g_print("Device added: %s\n", name);
52 * gst_object_unref (device);
54 * case GST_MESSAGE_DEVICE_REMOVED:
55 * gst_message_parse_device_removed (message, &device);
56 * name = gst_device_get_display_name (device);
57 * g_print("Device removed: %s\n", name);
59 * gst_object_unref (device);
65 * return G_SOURCE_CONTINUE;
69 * setup_raw_video_source_device_monitor (void) {
70 * GstDeviceMonitor *monitor;
74 * monitor = gst_device_monitor_new ();
76 * bus = gst_device_monitor_get_bus (monitor);
77 * gst_bus_add_watch (bus, my_bus_func, NULL);
78 * gst_object_unref (bus);
80 * caps = gst_caps_new_empty_simple ("video/x-raw");
81 * gst_device_monitor_add_filter (monitor, "Video/Source", caps);
82 * gst_caps_unref (caps);
84 * gst_device_monitor_start (monitor);
98 #include "gst_private.h"
99 #include "gstdevicemonitor.h"
101 GST_DEBUG_CATEGORY_STATIC (devicemonitor_debug);
102 #define GST_CAT_DEFAULT devicemonitor_debug
104 struct _GstDeviceMonitorPrivate
110 GPtrArray *providers;
113 GList *started_providers;
120 #define DEFAULT_SHOW_ALL FALSE
127 G_DEFINE_TYPE_WITH_PRIVATE (GstDeviceMonitor, gst_device_monitor,
130 static void gst_device_monitor_dispose (GObject * object);
132 static guint gst_device_monitor_add_filter_unlocked (GstDeviceMonitor * monitor,
133 const gchar * classes, GstCaps * caps);
136 provider_hidden (GstDeviceProvider * provider, const gchar * hidden,
137 GstDeviceMonitor * monitor);
140 provider_unhidden (GstDeviceProvider * provider, const gchar * hidden,
141 GstDeviceMonitor * monitor);
151 static struct DeviceFilter *
152 device_filter_copy (struct DeviceFilter *filter)
154 struct DeviceFilter *copy = g_slice_new0 (struct DeviceFilter);
156 copy->classesv = g_strdupv (filter->classesv);
157 copy->caps = filter->caps ? gst_caps_ref (filter->caps) : NULL;
163 device_filter_free (struct DeviceFilter *filter)
165 g_strfreev (filter->classesv);
168 gst_caps_unref (filter->caps);
170 g_slice_free (struct DeviceFilter, filter);
174 gst_device_monitor_get_property (GObject * object, guint prop_id,
175 GValue * value, GParamSpec * pspec)
177 GstDeviceMonitor *monitor = GST_DEVICE_MONITOR (object);
181 g_value_set_boolean (value,
182 gst_device_monitor_get_show_all_devices (monitor));
185 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
191 gst_device_monitor_set_property (GObject * object, guint prop_id,
192 const GValue * value, GParamSpec * pspec)
194 GstDeviceMonitor *monitor = GST_DEVICE_MONITOR (object);
198 gst_device_monitor_set_show_all_devices (monitor,
199 g_value_get_boolean (value));
202 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
209 gst_device_monitor_class_init (GstDeviceMonitorClass * klass)
211 GObjectClass *object_class = G_OBJECT_CLASS (klass);
213 object_class->get_property = gst_device_monitor_get_property;
214 object_class->set_property = gst_device_monitor_set_property;
215 object_class->dispose = gst_device_monitor_dispose;
217 GST_DEBUG_CATEGORY_INIT (devicemonitor_debug, "devicemonitor", 0,
218 "debugging info for the device monitor");
219 g_object_class_install_property (object_class, PROP_SHOW_ALL,
220 g_param_spec_boolean ("show-all", "Show All",
221 "Show all devices, even those from hidden providers",
222 DEFAULT_SHOW_ALL, G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE));
225 /* must be called with monitor lock */
227 is_provider_hidden (GstDeviceMonitor * monitor, GList * hidden,
228 GstDeviceProvider * provider)
230 GstDeviceProviderFactory *factory;
232 if (monitor->priv->show_all)
235 factory = gst_device_provider_get_factory (provider);
236 if (g_list_find_custom (hidden, GST_OBJECT_NAME (factory),
237 (GCompareFunc) g_strcmp0))
243 /* must be called with monitor lock */
245 update_hidden_providers_list (GList ** hidden, GstDeviceProvider * provider)
249 obs = gst_device_provider_get_hidden_providers (provider);
253 for (i = 0; obs[i]; i++)
254 *hidden = g_list_prepend (*hidden, obs[i]);
261 bus_sync_message (GstBus * bus, GstMessage * message,
262 GstDeviceMonitor * monitor)
264 GstMessageType type = GST_MESSAGE_TYPE (message);
266 if (type == GST_MESSAGE_DEVICE_ADDED || type == GST_MESSAGE_DEVICE_REMOVED ||
267 type == GST_MESSAGE_DEVICE_CHANGED) {
268 gboolean matches = TRUE;
270 GstDeviceProvider *provider;
272 if (type == GST_MESSAGE_DEVICE_ADDED)
273 gst_message_parse_device_added (message, &device);
274 else if (type == GST_MESSAGE_DEVICE_REMOVED)
275 gst_message_parse_device_removed (message, &device);
277 gst_message_parse_device_changed (message, &device, NULL);
279 GST_OBJECT_LOCK (monitor);
281 GST_DEVICE_PROVIDER (gst_object_get_parent (GST_OBJECT (device)));
282 if (is_provider_hidden (monitor, monitor->priv->hidden, provider)) {
287 for (i = 0; i < monitor->priv->filters->len; i++) {
288 struct DeviceFilter *filter =
289 g_ptr_array_index (monitor->priv->filters, i);
292 caps = gst_device_get_caps (device);
293 matches = gst_caps_can_intersect (filter->caps, caps) &&
294 gst_device_has_classesv (device, filter->classesv);
295 gst_caps_unref (caps);
300 GST_OBJECT_UNLOCK (monitor);
302 gst_object_unref (provider);
303 gst_object_unref (device);
306 gst_bus_post (monitor->priv->bus, gst_message_ref (message));
312 gst_device_monitor_init (GstDeviceMonitor * self)
314 self->priv = gst_device_monitor_get_instance_private (self);
316 self->priv->show_all = DEFAULT_SHOW_ALL;
318 self->priv->bus = gst_bus_new ();
319 gst_bus_set_flushing (self->priv->bus, TRUE);
321 self->priv->providers = g_ptr_array_new ();
322 self->priv->filters = g_ptr_array_new_with_free_func (
323 (GDestroyNotify) device_filter_free);
325 self->priv->last_id = 1;
330 gst_device_monitor_remove_provider (GstDeviceMonitor * self, guint i)
332 GstDeviceProvider *provider = g_ptr_array_index (self->priv->providers, i);
335 g_ptr_array_remove_index (self->priv->providers, i);
337 bus = gst_device_provider_get_bus (provider);
338 g_signal_handlers_disconnect_by_func (bus, bus_sync_message, self);
339 gst_object_unref (bus);
341 g_signal_handlers_disconnect_by_func (provider, provider_hidden, self);
342 g_signal_handlers_disconnect_by_func (provider, provider_unhidden, self);
344 gst_object_unref (provider);
348 gst_device_monitor_dispose (GObject * object)
350 GstDeviceMonitor *self = GST_DEVICE_MONITOR (object);
352 g_return_if_fail (!self->priv->started);
354 if (self->priv->providers) {
355 while (self->priv->providers->len)
356 gst_device_monitor_remove_provider (self, self->priv->providers->len - 1);
357 g_ptr_array_unref (self->priv->providers);
358 self->priv->providers = NULL;
361 if (self->priv->filters) {
362 g_ptr_array_unref (self->priv->filters);
363 self->priv->filters = NULL;
366 if (self->priv->hidden) {
367 g_list_free_full (self->priv->hidden, g_free);
368 self->priv->hidden = NULL;
371 gst_object_replace ((GstObject **) & self->priv->bus, NULL);
373 G_OBJECT_CLASS (gst_device_monitor_parent_class)->dispose (object);
377 * gst_device_monitor_get_devices:
378 * @monitor: A #GstDeviceProvider
380 * Gets a list of devices from all of the relevant monitors. This may actually
381 * probe the hardware if the monitor is not currently started.
383 * Returns: (transfer full) (element-type GstDevice) (nullable): a #GList of
390 gst_device_monitor_get_devices (GstDeviceMonitor * monitor)
392 GQueue providers = G_QUEUE_INIT, filters = G_QUEUE_INIT;
393 GList *hidden = NULL;
394 GQueue devices = G_QUEUE_INIT;
398 g_return_val_if_fail (GST_IS_DEVICE_MONITOR (monitor), NULL);
400 GST_OBJECT_LOCK (monitor);
402 if (monitor->priv->filters->len == 0) {
403 GST_OBJECT_UNLOCK (monitor);
404 GST_WARNING_OBJECT (monitor, "No filters have been set");
408 if (monitor->priv->providers->len == 0) {
409 GST_OBJECT_UNLOCK (monitor);
410 GST_WARNING_OBJECT (monitor, "No providers match the current filters");
414 for (i = 0; i < monitor->priv->providers->len; i++) {
415 GstDeviceProvider *provider =
416 g_ptr_array_index (monitor->priv->providers, i);
418 update_hidden_providers_list (&hidden, provider);
421 /* Create a copy of all current providers and filters while keeping the lock
422 * and afterwards unlock and work with this snapshot */
423 for (i = 0; i < monitor->priv->providers->len; i++) {
424 GstDeviceProvider *provider =
425 g_ptr_array_index (monitor->priv->providers, i);
427 if (!is_provider_hidden (monitor, hidden, provider)) {
428 g_queue_push_tail (&providers, gst_object_ref (provider));
432 for (i = 0; i < monitor->priv->filters->len; i++) {
433 struct DeviceFilter *filter = g_ptr_array_index (monitor->priv->filters, i);
435 g_queue_push_tail (&filters, device_filter_copy (filter));
437 GST_OBJECT_UNLOCK (monitor);
439 for (l = providers.head; l; l = l->next) {
440 GstDeviceProvider *provider = l->data;
441 GList *tmpdev, *item, *filter_item;
443 tmpdev = gst_device_provider_get_devices (provider);
445 for (item = tmpdev; item; item = item->next) {
446 GstDevice *dev = GST_DEVICE (item->data);
447 GstCaps *caps = gst_device_get_caps (dev);
449 for (filter_item = filters.head; filter_item;
450 filter_item = filter_item->next) {
451 struct DeviceFilter *filter = filter_item->data;
453 if (gst_caps_can_intersect (filter->caps, caps) &&
454 gst_device_has_classesv (dev, filter->classesv)) {
455 g_queue_push_tail (&devices, gst_object_ref (dev));
459 gst_caps_unref (caps);
462 g_list_free_full (tmpdev, gst_object_unref);
464 g_list_free_full (hidden, g_free);
466 g_queue_clear_full (&providers, (GDestroyNotify) gst_object_unref);
467 g_queue_clear_full (&filters, (GDestroyNotify) device_filter_free);
473 * gst_device_monitor_start:
474 * @monitor: A #GstDeviceMonitor
476 * Starts monitoring the devices, one this has succeeded, the
477 * %GST_MESSAGE_DEVICE_ADDED and %GST_MESSAGE_DEVICE_REMOVED messages
478 * will be emitted on the bus when the list of devices changes.
480 * Returns: %TRUE if the device monitoring could be started, i.e. at least a
481 * single device provider was started successfully.
487 gst_device_monitor_start (GstDeviceMonitor * monitor)
490 GQueue pending = G_QUEUE_INIT;
491 GList *started = NULL;
492 GstDeviceProvider *provider;
494 g_return_val_if_fail (GST_IS_DEVICE_MONITOR (monitor), FALSE);
496 GST_OBJECT_LOCK (monitor);
498 if (monitor->priv->started) {
499 GST_OBJECT_UNLOCK (monitor);
500 GST_DEBUG_OBJECT (monitor, "Monitor started already");
503 if (monitor->priv->filters->len == 0) {
504 GST_WARNING_OBJECT (monitor, "No filters have been set, will expose all "
506 gst_device_monitor_add_filter_unlocked (monitor, NULL, NULL);
509 if (monitor->priv->providers->len == 0) {
510 GST_OBJECT_UNLOCK (monitor);
511 GST_WARNING_OBJECT (monitor, "No providers match the current filters");
515 monitor->priv->started = TRUE;
517 gst_bus_set_flushing (monitor->priv->bus, FALSE);
519 for (i = 0; i < monitor->priv->providers->len; i++) {
520 GstDeviceProvider *provider;
522 provider = g_ptr_array_index (monitor->priv->providers, i);
523 g_queue_push_tail (&pending, gst_object_ref (provider));
526 while ((provider = g_queue_pop_head (&pending))) {
527 GST_OBJECT_UNLOCK (monitor);
529 if (gst_device_provider_start (provider)) {
530 started = g_list_prepend (started, provider);
532 gst_object_unref (provider);
535 GST_OBJECT_LOCK (monitor);
539 monitor->priv->started_providers = started;
541 gst_bus_set_flushing (monitor->priv->bus, TRUE);
542 monitor->priv->started = FALSE;
545 GST_OBJECT_UNLOCK (monitor);
547 return started != NULL;
551 * gst_device_monitor_stop:
552 * @monitor: A #GstDeviceProvider
554 * Stops monitoring the devices.
559 gst_device_monitor_stop (GstDeviceMonitor * monitor)
561 GList *started = NULL;
563 g_return_if_fail (GST_IS_DEVICE_MONITOR (monitor));
565 gst_bus_set_flushing (monitor->priv->bus, TRUE);
567 GST_OBJECT_LOCK (monitor);
568 if (!monitor->priv->started) {
569 GST_DEBUG_OBJECT (monitor, "Monitor was not started yet");
570 GST_OBJECT_UNLOCK (monitor);
574 started = monitor->priv->started_providers;
575 monitor->priv->started_providers = NULL;
576 monitor->priv->started = FALSE;
577 GST_OBJECT_UNLOCK (monitor);
580 GstDeviceProvider *provider = started->data;
582 gst_device_provider_stop (provider);
584 started = g_list_delete_link (started, started);
585 gst_object_unref (provider);
590 provider_hidden (GstDeviceProvider * provider, const gchar * hidden,
591 GstDeviceMonitor * monitor)
593 GST_OBJECT_LOCK (monitor);
594 monitor->priv->hidden =
595 g_list_prepend (monitor->priv->hidden, g_strdup (hidden));
596 GST_OBJECT_UNLOCK (monitor);
600 provider_unhidden (GstDeviceProvider * provider, const gchar * hidden,
601 GstDeviceMonitor * monitor)
605 GST_OBJECT_LOCK (monitor);
607 g_list_find_custom (monitor->priv->hidden, hidden,
608 (GCompareFunc) g_strcmp0);
611 monitor->priv->hidden = g_list_delete_link (monitor->priv->hidden, find);
613 GST_OBJECT_UNLOCK (monitor);
617 * gst_device_monitor_add_filter:
618 * @monitor: a device monitor
619 * @classes: (allow-none): device classes to use as filter or %NULL for any class
620 * @caps: (allow-none): the #GstCaps to filter or %NULL for ANY
622 * Adds a filter for which #GstDevice will be monitored, any device that matches
623 * all these classes and the #GstCaps will be returned.
625 * If this function is called multiple times to add more filters, each will be
626 * matched independently. That is, adding more filters will not further restrict
627 * what devices are matched.
629 * The #GstCaps supported by the device as returned by gst_device_get_caps() are
630 * not intersected with caps filters added using this function.
632 * Filters must be added before the #GstDeviceMonitor is started.
634 * Returns: The id of the new filter or 0 if no provider matched the filter's
640 gst_device_monitor_add_filter (GstDeviceMonitor * monitor,
641 const gchar * classes, GstCaps * caps)
645 g_return_val_if_fail (GST_IS_DEVICE_MONITOR (monitor), 0);
646 g_return_val_if_fail (!monitor->priv->started, 0);
648 GST_OBJECT_LOCK (monitor);
649 id = gst_device_monitor_add_filter_unlocked (monitor, classes, caps);
650 GST_OBJECT_UNLOCK (monitor);
656 gst_device_monitor_add_filter_unlocked (GstDeviceMonitor * monitor,
657 const gchar * classes, GstCaps * caps)
659 GList *factories = NULL;
660 struct DeviceFilter *filter;
662 gboolean matched = FALSE;
664 filter = g_slice_new0 (struct DeviceFilter);
665 filter->id = monitor->priv->last_id++;
667 filter->caps = gst_caps_ref (caps);
669 filter->caps = gst_caps_new_any ();
671 filter->classesv = g_strsplit (classes, "/", 0);
673 factories = gst_device_provider_factory_list_get_device_providers (1);
676 GstDeviceProviderFactory *factory = factories->data;
678 if (gst_device_provider_factory_has_classesv (factory, filter->classesv)) {
679 GstDeviceProvider *provider;
681 provider = gst_device_provider_factory_get (factory);
686 for (i = 0; i < monitor->priv->providers->len; i++) {
687 if (g_ptr_array_index (monitor->priv->providers, i) == provider) {
688 gst_object_unref (provider);
697 GstBus *bus = gst_device_provider_get_bus (provider);
699 update_hidden_providers_list (&monitor->priv->hidden, provider);
700 g_signal_connect (provider, "provider-hidden",
701 (GCallback) provider_hidden, monitor);
702 g_signal_connect (provider, "provider-unhidden",
703 (GCallback) provider_unhidden, monitor);
706 gst_bus_enable_sync_message_emission (bus);
707 g_signal_connect (bus, "sync-message",
708 G_CALLBACK (bus_sync_message), monitor);
709 gst_object_unref (bus);
710 g_ptr_array_add (monitor->priv->providers, provider);
714 factories = g_list_remove (factories, factory);
715 gst_object_unref (factory);
718 /* Ensure there is no leak here */
719 g_assert (factories == NULL);
723 g_ptr_array_add (monitor->priv->filters, filter);
729 * gst_device_monitor_remove_filter:
730 * @monitor: a device monitor
731 * @filter_id: the id of the filter
733 * Removes a filter from the #GstDeviceMonitor using the id that was returned
734 * by gst_device_monitor_add_filter().
736 * Returns: %TRUE of the filter id was valid, %FALSE otherwise
741 gst_device_monitor_remove_filter (GstDeviceMonitor * monitor, guint filter_id)
744 gboolean removed = FALSE;
746 g_return_val_if_fail (GST_IS_DEVICE_MONITOR (monitor), FALSE);
747 g_return_val_if_fail (!monitor->priv->started, FALSE);
748 g_return_val_if_fail (filter_id > 0, FALSE);
750 GST_OBJECT_LOCK (monitor);
751 for (i = 0; i < monitor->priv->filters->len; i++) {
752 struct DeviceFilter *filter = g_ptr_array_index (monitor->priv->filters, i);
754 if (filter->id == filter_id) {
755 g_ptr_array_remove_index (monitor->priv->filters, i);
762 for (i = 0; i < monitor->priv->providers->len; i++) {
763 GstDeviceProvider *provider =
764 g_ptr_array_index (monitor->priv->providers, i);
765 GstDeviceProviderFactory *factory =
766 gst_device_provider_get_factory (provider);
767 gboolean valid = FALSE;
769 for (j = 0; j < monitor->priv->filters->len; j++) {
770 struct DeviceFilter *filter =
771 g_ptr_array_index (monitor->priv->filters, j);
773 if (gst_device_provider_factory_has_classesv (factory,
781 gst_device_monitor_remove_provider (monitor, i);
787 GST_OBJECT_UNLOCK (monitor);
795 * gst_device_monitor_new:
797 * Create a new #GstDeviceMonitor
799 * Returns: (transfer full): a new device monitor.
804 gst_device_monitor_new (void)
806 GstDeviceMonitor *monitor;
808 monitor = g_object_new (GST_TYPE_DEVICE_MONITOR, NULL);
810 /* Clear floating flag */
811 gst_object_ref_sink (monitor);
817 * gst_device_monitor_get_bus:
818 * @monitor: a #GstDeviceProvider
820 * Gets the #GstBus of this #GstDeviceMonitor
822 * Returns: (transfer full): a #GstBus
827 gst_device_monitor_get_bus (GstDeviceMonitor * monitor)
829 g_return_val_if_fail (GST_IS_DEVICE_MONITOR (monitor), NULL);
831 return gst_object_ref (monitor->priv->bus);
835 * gst_device_monitor_get_providers:
836 * @monitor: a #GstDeviceMonitor
838 * Get a list of the currently selected device provider factories.
842 * Returns: (transfer full) (array zero-terminated=1) (element-type gchar*):
843 * A list of device provider factory names that are currently being
844 * monitored by @monitor or %NULL when nothing is being monitored.
849 gst_device_monitor_get_providers (GstDeviceMonitor * monitor)
854 g_return_val_if_fail (GST_IS_DEVICE_MONITOR (monitor), NULL);
856 GST_OBJECT_LOCK (monitor);
857 len = monitor->priv->providers->len;
861 res = g_new (gchar *, len + 1);
863 for (i = 0; i < len; i++) {
864 GstDeviceProvider *provider =
865 g_ptr_array_index (monitor->priv->providers, i);
866 GstDeviceProviderFactory *factory =
867 gst_device_provider_get_factory (provider);
869 res[i] = g_strdup (GST_OBJECT_NAME (factory));
874 GST_OBJECT_UNLOCK (monitor);
880 * gst_device_monitor_set_show_all_devices:
881 * @monitor: a #GstDeviceMonitor
882 * @show_all: show all devices
884 * Set if all devices should be visible, even those devices from hidden
885 * providers. Setting @show_all to true might show some devices multiple times.
890 gst_device_monitor_set_show_all_devices (GstDeviceMonitor * monitor,
893 g_return_if_fail (GST_IS_DEVICE_MONITOR (monitor));
895 GST_OBJECT_LOCK (monitor);
896 monitor->priv->show_all = show_all;
897 GST_OBJECT_UNLOCK (monitor);
901 * gst_device_monitor_get_show_all_devices:
902 * @monitor: a #GstDeviceMonitor
904 * Get if @monitor is currently showing all devices, even those from hidden
907 * Returns: %TRUE when all devices will be shown.
912 gst_device_monitor_get_show_all_devices (GstDeviceMonitor * monitor)
916 g_return_val_if_fail (GST_IS_DEVICE_MONITOR (monitor), FALSE);
918 GST_OBJECT_LOCK (monitor);
919 res = monitor->priv->show_all;
920 GST_OBJECT_UNLOCK (monitor);