gst/gstdeviceprovider.c

   1 /* GStreamer
   2  * Copyright (C) 2012 Olivier Crete <olivier.crete@collabora.com>
   3  *
   4  * gstdeviceprovider.c: Device probing and monitoring
   5  *
   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.
  10  *
  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.
  15  *
  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.
  20  */
  21
  22 /**
  23  * SECTION:gstdeviceprovider
  24  * @title: GstDeviceProvider
  25  * @short_description: A device provider
  26  * @see_also: #GstDevice, #GstDeviceMonitor
  27  *
  28  * A #GstDeviceProvider subclass is provided by a plugin that handles devices
  29  * if there is a way to programmatically list connected devices. It can also
  30  * optionally provide updates to the list of connected devices.
  31  *
  32  * Each #GstDeviceProvider subclass is a singleton, a plugin should
  33  * normally provide a single subclass for all devices.
  34  *
  35  * Applications would normally use a #GstDeviceMonitor to monitor devices
  36  * from all relevant providers.
  37  *
  38  * Since: 1.4
  39  */
  40
  41 #ifdef HAVE_CONFIG_H
  42 #include "config.h"
  43 #endif
  44
  45 #include "gst_private.h"
  46
  47 #include "gstdeviceprovider.h"
  48
  49 #include "gstelementmetadata.h"
  50 #include "gstquark.h"
  51
  52 struct _GstDeviceProviderPrivate
  53 {
  54   GstBus *bus;
  55
  56   GMutex start_lock;
  57
  58   gboolean started_count;
  59
  60   GList *hidden_providers;
  61 };
  62
  63 enum
  64 {
  65   PROVIDER_HIDDEN,
  66   PROVIDER_UNHIDDEN,
  67   LAST_SIGNAL
  68 };
  69
  70 static guint gst_device_provider_signals[LAST_SIGNAL] = { 0 };
  71
  72 /* this is used in gstelementfactory.c:gst_element_register() */
  73 GQuark __gst_deviceproviderclass_factory = 0;
  74
  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);
  80
  81 static gpointer gst_device_provider_parent_class = NULL;
  82 static gint private_offset = 0;
  83
  84 GType
  85 gst_device_provider_get_type (void)
  86 {
  87   static volatile gsize gst_device_provider_type = 0;
  88
  89   if (g_once_init_enter (&gst_device_provider_type)) {
  90     GType _type;
  91     static const GTypeInfo element_info = {
  92       sizeof (GstDeviceProviderClass),
  93       gst_device_provider_base_class_init,
  94       NULL,                     /* base_class_finalize */
  95       (GClassInitFunc) gst_device_provider_class_init,
  96       NULL,
  97       NULL,
  98       sizeof (GstDeviceProvider),
  99       0,
 100       (GInstanceInitFunc) gst_device_provider_init,
 101       NULL
 102     };
 103
 104     _type = g_type_register_static (GST_TYPE_OBJECT, "GstDeviceProvider",
 105         &element_info, G_TYPE_FLAG_ABSTRACT);
 106
 107     private_offset =
 108         g_type_add_instance_private (_type, sizeof (GstDeviceProviderPrivate));
 109
 110     __gst_deviceproviderclass_factory =
 111         g_quark_from_static_string ("GST_DEVICEPROVIDERCLASS_FACTORY");
 112     g_once_init_leave (&gst_device_provider_type, _type);
 113   }
 114   return gst_device_provider_type;
 115 }
 116
 117 static inline gpointer
 118 gst_device_provider_get_instance_private (GstDeviceProvider * self)
 119 {
 120   return (G_STRUCT_MEMBER_P (self, private_offset));
 121 }
 122
 123 static void
 124 gst_device_provider_base_class_init (gpointer g_class)
 125 {
 126   GstDeviceProviderClass *klass = GST_DEVICE_PROVIDER_CLASS (g_class);
 127
 128   /* Copy the element details here so elements can inherit the
 129    * details from their base class and classes only need to set
 130    * the details in class_init instead of base_init */
 131   klass->metadata =
 132       klass->metadata ? gst_structure_copy (klass->metadata) :
 133       gst_structure_new_empty ("metadata");
 134
 135   klass->factory = g_type_get_qdata (G_TYPE_FROM_CLASS (klass),
 136       __gst_deviceproviderclass_factory);
 137 }
 138
 139 static void
 140 gst_device_provider_class_init (GstDeviceProviderClass * klass)
 141 {
 142   GObjectClass *gobject_class = (GObjectClass *) klass;
 143
 144   gst_device_provider_parent_class = g_type_class_peek_parent (klass);
 145
 146   if (private_offset != 0)
 147     g_type_class_adjust_private_offset (klass, &private_offset);
 148
 149   gobject_class->dispose = gst_device_provider_dispose;
 150   gobject_class->finalize = gst_device_provider_finalize;
 151
 152   gst_device_provider_signals[PROVIDER_HIDDEN] =
 153       g_signal_new ("provider-hidden", G_TYPE_FROM_CLASS (klass),
 154       G_SIGNAL_RUN_FIRST, 0, NULL,
 155       NULL, g_cclosure_marshal_generic, G_TYPE_NONE, 1, G_TYPE_STRING);
 156
 157   gst_device_provider_signals[PROVIDER_UNHIDDEN] =
 158       g_signal_new ("provider-unhidden", G_TYPE_FROM_CLASS (klass),
 159       G_SIGNAL_RUN_FIRST, 0, NULL,
 160       NULL, g_cclosure_marshal_generic, G_TYPE_NONE, 1, G_TYPE_STRING);
 161 }
 162
 163 static void
 164 gst_device_provider_init (GstDeviceProvider * provider)
 165 {
 166   provider->priv = gst_device_provider_get_instance_private (provider);
 167
 168   g_mutex_init (&provider->priv->start_lock);
 169
 170   provider->priv->bus = gst_bus_new ();
 171   gst_bus_set_flushing (provider->priv->bus, TRUE);
 172 }
 173
 174
 175 static void
 176 gst_device_provider_dispose (GObject * object)
 177 {
 178   GstDeviceProvider *provider = GST_DEVICE_PROVIDER (object);
 179
 180   gst_object_replace ((GstObject **) & provider->priv->bus, NULL);
 181
 182   GST_OBJECT_LOCK (provider);
 183   g_list_free_full (provider->devices, (GDestroyNotify) gst_object_unparent);
 184   provider->devices = NULL;
 185   GST_OBJECT_UNLOCK (provider);
 186
 187   G_OBJECT_CLASS (gst_device_provider_parent_class)->dispose (object);
 188 }
 189
 190 static void
 191 gst_device_provider_finalize (GObject * object)
 192 {
 193   GstDeviceProvider *provider = GST_DEVICE_PROVIDER (object);
 194
 195   g_mutex_clear (&provider->priv->start_lock);
 196
 197   G_OBJECT_CLASS (gst_device_provider_parent_class)->finalize (object);
 198 }
 199
 200 /**
 201  * gst_device_provider_class_add_metadata:
 202  * @klass: class to set metadata for
 203  * @key: the key to set
 204  * @value: the value to set
 205  *
 206  * Set @key with @value as metadata in @klass.
 207  *
 208  * Since: 1.4
 209  */
 210 void
 211 gst_device_provider_class_add_metadata (GstDeviceProviderClass * klass,
 212     const gchar * key, const gchar * value)
 213 {
 214   g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
 215   g_return_if_fail (key != NULL);
 216   g_return_if_fail (value != NULL);
 217
 218   gst_structure_set ((GstStructure *) klass->metadata,
 219       key, G_TYPE_STRING, value, NULL);
 220 }
 221
 222 /**
 223  * gst_device_provider_class_add_static_metadata:
 224  * @klass: class to set metadata for
 225  * @key: the key to set
 226  * @value: (transfer full): the value to set
 227  *
 228  * Set @key with @value as metadata in @klass.
 229  *
 230  * Same as gst_device_provider_class_add_metadata(), but @value must be a static string
 231  * or an inlined string, as it will not be copied. (GStreamer plugins will
 232  * be made resident once loaded, so this function can be used even from
 233  * dynamically loaded plugins.)
 234  *
 235  * Since: 1.4
 236  */
 237 void
 238 gst_device_provider_class_add_static_metadata (GstDeviceProviderClass * klass,
 239     const gchar * key, const gchar * value)
 240 {
 241   GValue val = G_VALUE_INIT;
 242
 243   g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
 244   g_return_if_fail (key != NULL);
 245   g_return_if_fail (value != NULL);
 246
 247   g_value_init (&val, G_TYPE_STRING);
 248   g_value_set_static_string (&val, value);
 249   gst_structure_take_value ((GstStructure *) klass->metadata, key, &val);
 250 }
 251
 252 /**
 253  * gst_device_provider_class_set_metadata:
 254  * @klass: class to set metadata for
 255  * @longname: The long English name of the device provider. E.g. "File Sink"
 256  * @classification: String describing the type of device provider, as an
 257  *  unordered list separated with slashes ('/'). See draft-klass.txt of the
 258  *  design docs
 259  * for more details and common types. E.g: "Sink/File"
 260  * @description: Sentence describing the purpose of the device provider.
 261  * E.g: "Write stream to a file"
 262  * @author: Name and contact details of the author(s). Use \n to separate
 263  * multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
 264  *
 265  * Sets the detailed information for a #GstDeviceProviderClass.
 266  *
 267  * > This function is for use in _class_init functions only.
 268  *
 269  * Since: 1.4
 270  */
 271 void
 272 gst_device_provider_class_set_metadata (GstDeviceProviderClass * klass,
 273     const gchar * longname, const gchar * classification,
 274     const gchar * description, const gchar * author)
 275 {
 276   g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
 277   g_return_if_fail (longname != NULL && *longname != '\0');
 278   g_return_if_fail (classification != NULL && *classification != '\0');
 279   g_return_if_fail (description != NULL && *description != '\0');
 280   g_return_if_fail (author != NULL && *author != '\0');
 281
 282   gst_structure_id_set ((GstStructure *) klass->metadata,
 283       GST_QUARK (ELEMENT_METADATA_LONGNAME), G_TYPE_STRING, longname,
 284       GST_QUARK (ELEMENT_METADATA_KLASS), G_TYPE_STRING, classification,
 285       GST_QUARK (ELEMENT_METADATA_DESCRIPTION), G_TYPE_STRING, description,
 286       GST_QUARK (ELEMENT_METADATA_AUTHOR), G_TYPE_STRING, author, NULL);
 287 }
 288
 289 /**
 290  * gst_device_provider_class_set_static_metadata:
 291  * @klass: class to set metadata for
 292  * @longname: (transfer full): The long English name of the element. E.g. "File Sink"
 293  * @classification: (transfer full): String describing the type of element, as
 294  * an unordered list separated with slashes ('/'). See draft-klass.txt of the
 295  * design docs for more details and common types. E.g: "Sink/File"
 296  * @description: (transfer full): Sentence describing the purpose of the
 297  * element.  E.g: "Write stream to a file"
 298  * @author: (transfer full): Name and contact details of the author(s). Use \n
 299  * to separate multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at
 300  * foo.com&gt;"
 301  *
 302  * Sets the detailed information for a #GstDeviceProviderClass.
 303  *
 304  * > This function is for use in _class_init functions only.
 305  *
 306  * Same as gst_device_provider_class_set_metadata(), but @longname, @classification,
 307  * @description, and @author must be static strings or inlined strings, as
 308  * they will not be copied. (GStreamer plugins will be made resident once
 309  * loaded, so this function can be used even from dynamically loaded plugins.)
 310  *
 311  * Since: 1.4
 312  */
 313 void
 314 gst_device_provider_class_set_static_metadata (GstDeviceProviderClass * klass,
 315     const gchar * longname, const gchar * classification,
 316     const gchar * description, const gchar * author)
 317 {
 318   GstStructure *s = (GstStructure *) klass->metadata;
 319   GValue val = G_VALUE_INIT;
 320
 321   g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
 322   g_return_if_fail (longname != NULL && *longname != '\0');
 323   g_return_if_fail (classification != NULL && *classification != '\0');
 324   g_return_if_fail (description != NULL && *description != '\0');
 325   g_return_if_fail (author != NULL && *author != '\0');
 326
 327   g_value_init (&val, G_TYPE_STRING);
 328
 329   g_value_set_static_string (&val, longname);
 330   gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_LONGNAME), &val);
 331
 332   g_value_set_static_string (&val, classification);
 333   gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_KLASS), &val);
 334
 335   g_value_set_static_string (&val, description);
 336   gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_DESCRIPTION),
 337       &val);
 338
 339   g_value_set_static_string (&val, author);
 340   gst_structure_id_take_value (s, GST_QUARK (ELEMENT_METADATA_AUTHOR), &val);
 341 }
 342
 343 /**
 344  * gst_device_provider_class_get_metadata:
 345  * @klass: class to get metadata for
 346  * @key: the key to get
 347  *
 348  * Get metadata with @key in @klass.
 349  *
 350  * Returns: (nullable): the metadata for @key.
 351  *
 352  * Since: 1.4
 353  */
 354 const gchar *
 355 gst_device_provider_class_get_metadata (GstDeviceProviderClass * klass,
 356     const gchar * key)
 357 {
 358   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass), NULL);
 359   g_return_val_if_fail (key != NULL, NULL);
 360
 361   return gst_structure_get_string ((GstStructure *) klass->metadata, key);
 362 }
 363
 364 /**
 365  * gst_device_provider_get_metadata:
 366  * @provider: provider to get metadata for
 367  * @key: the key to get
 368  *
 369  * Get metadata with @key in @provider.
 370  *
 371  * Returns: the metadata for @key.
 372  *
 373  * Since: 1.14
 374  */
 375 const gchar *
 376 gst_device_provider_get_metadata (GstDeviceProvider * provider,
 377     const gchar * key)
 378 {
 379   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
 380   g_return_val_if_fail (key != NULL, NULL);
 381
 382   return
 383       gst_device_provider_class_get_metadata (GST_DEVICE_PROVIDER_GET_CLASS
 384       (provider), key);
 385 }
 386
 387 /**
 388  * gst_device_provider_get_devices:
 389  * @provider: A #GstDeviceProvider
 390  *
 391  * Gets a list of devices that this provider understands. This may actually
 392  * probe the hardware if the provider is not currently started.
 393  *
 394  * Returns: (transfer full) (element-type GstDevice): a #GList of
 395  *   #GstDevice
 396  *
 397  * Since: 1.4
 398  */
 399
 400 GList *
 401 gst_device_provider_get_devices (GstDeviceProvider * provider)
 402 {
 403   GstDeviceProviderClass *klass;
 404   GList *devices = NULL;
 405   gboolean started;
 406   GList *item;
 407
 408   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
 409   klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
 410
 411   g_mutex_lock (&provider->priv->start_lock);
 412   started = (provider->priv->started_count > 0);
 413
 414   if (started) {
 415     GST_OBJECT_LOCK (provider);
 416     for (item = provider->devices; item; item = item->next)
 417       devices = g_list_prepend (devices, gst_object_ref (item->data));
 418     GST_OBJECT_UNLOCK (provider);
 419   } else if (klass->probe)
 420     devices = klass->probe (provider);
 421
 422   g_mutex_unlock (&provider->priv->start_lock);
 423
 424   return devices;
 425 }
 426
 427 /**
 428  * gst_device_provider_start:
 429  * @provider: A #GstDeviceProvider
 430  *
 431  * Starts providering the devices. This will cause #GST_MESSAGE_DEVICE_ADDED
 432  * and #GST_MESSAGE_DEVICE_REMOVED messages to be posted on the provider's bus
 433  * when devices are added or removed from the system.
 434  *
 435  * Since the #GstDeviceProvider is a singleton,
 436  * gst_device_provider_start() may already have been called by another
 437  * user of the object, gst_device_provider_stop() needs to be called the same
 438  * number of times.
 439  *
 440  * Returns: %TRUE if the device providering could be started
 441  *
 442  * Since: 1.4
 443  */
 444
 445 gboolean
 446 gst_device_provider_start (GstDeviceProvider * provider)
 447 {
 448   GstDeviceProviderClass *klass;
 449   gboolean ret = FALSE;
 450
 451   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), FALSE);
 452   klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
 453
 454   g_mutex_lock (&provider->priv->start_lock);
 455
 456   if (provider->priv->started_count > 0) {
 457     provider->priv->started_count++;
 458     ret = TRUE;
 459     goto started;
 460   }
 461
 462   if (klass->start)
 463     ret = klass->start (provider);
 464
 465   if (ret) {
 466     provider->priv->started_count++;
 467     gst_bus_set_flushing (provider->priv->bus, FALSE);
 468   }
 469
 470 started:
 471
 472   g_mutex_unlock (&provider->priv->start_lock);
 473
 474   return ret;
 475 }
 476
 477 /**
 478  * gst_device_provider_stop:
 479  * @provider: A #GstDeviceProvider
 480  *
 481  * Decreases the use-count by one. If the use count reaches zero, this
 482  * #GstDeviceProvider will stop providering the devices. This needs to be
 483  * called the same number of times that gst_device_provider_start() was called.
 484  *
 485  * Since: 1.4
 486  */
 487
 488 void
 489 gst_device_provider_stop (GstDeviceProvider * provider)
 490 {
 491   GstDeviceProviderClass *klass;
 492
 493   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 494   klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
 495
 496   g_mutex_lock (&provider->priv->start_lock);
 497
 498   if (provider->priv->started_count == 1) {
 499     gst_bus_set_flushing (provider->priv->bus, TRUE);
 500     if (klass->stop)
 501       klass->stop (provider);
 502     GST_OBJECT_LOCK (provider);
 503     g_list_free_full (provider->devices, (GDestroyNotify) gst_object_unparent);
 504     provider->devices = NULL;
 505     GST_OBJECT_UNLOCK (provider);
 506   } else if (provider->priv->started_count < 1) {
 507     g_critical
 508         ("Trying to stop a GstDeviceProvider %s which is already stopped",
 509         GST_OBJECT_NAME (provider));
 510   }
 511
 512   provider->priv->started_count--;
 513   g_mutex_unlock (&provider->priv->start_lock);
 514 }
 515
 516
 517 /**
 518  * gst_device_provider_get_factory:
 519  * @provider: a #GstDeviceProvider to request the device provider factory of.
 520  *
 521  * Retrieves the factory that was used to create this device provider.
 522  *
 523  * Returns: (transfer none): the #GstDeviceProviderFactory used for
 524  *     creating this device provider. no refcounting is needed.
 525  *
 526  * Since: 1.4
 527  */
 528 GstDeviceProviderFactory *
 529 gst_device_provider_get_factory (GstDeviceProvider * provider)
 530 {
 531   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
 532
 533   return GST_DEVICE_PROVIDER_GET_CLASS (provider)->factory;
 534 }
 535
 536 /**
 537  * gst_device_provider_can_provider:
 538  * @provider: a #GstDeviceProvider
 539  *
 540  * If this function returns %TRUE, then the device provider can provider if
 541  * devices are added or removed. Otherwise, it can only do static probing.
 542  *
 543  * Returns: %TRUE if the #GstDeviceProvider support providering, %FALSE otherwise
 544  */
 545 gboolean
 546 gst_device_provider_can_monitor (GstDeviceProvider * provider)
 547 {
 548   GstDeviceProviderClass *klass;
 549
 550   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), FALSE);
 551   klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
 552
 553   if (klass->start)
 554     return TRUE;
 555   else
 556     return FALSE;
 557 }
 558
 559 /**
 560  * gst_device_provider_get_bus:
 561  * @provider: a #GstDeviceProvider
 562  *
 563  * Gets the #GstBus of this #GstDeviceProvider
 564  *
 565  * Returns: (transfer full): a #GstBus
 566  *
 567  * Since: 1.4
 568  */
 569 GstBus *
 570 gst_device_provider_get_bus (GstDeviceProvider * provider)
 571 {
 572   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
 573
 574   return gst_object_ref (provider->priv->bus);
 575 }
 576
 577 /**
 578  * gst_device_provider_device_add:
 579  * @provider: a #GstDeviceProvider
 580  * @device: (transfer floating): a #GstDevice that has been added
 581  *
 582  * Posts a message on the provider's #GstBus to inform applications that
 583  * a new device has been added.
 584  *
 585  * This is for use by subclasses.
 586  *
 587  * @device's reference count will be incremented, and any floating reference
 588  * will be removed (see gst_object_ref_sink()).
 589  *
 590  * Since: 1.4
 591  */
 592 void
 593 gst_device_provider_device_add (GstDeviceProvider * provider,
 594     GstDevice * device)
 595 {
 596   GstMessage *message;
 597
 598   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 599   g_return_if_fail (GST_IS_DEVICE (device));
 600
 601   if (!gst_object_set_parent (GST_OBJECT (device), GST_OBJECT (provider))) {
 602     GST_WARNING_OBJECT (provider, "Could not parent device %p to provider,"
 603         " it already has a parent", device);
 604     return;
 605   }
 606
 607   GST_OBJECT_LOCK (provider);
 608   /* Take an additional reference so we can be sure nobody removed it from the
 609    * provider in the meantime and we can safely emit the message */
 610   gst_object_ref (device);
 611   provider->devices = g_list_prepend (provider->devices, device);
 612   GST_OBJECT_UNLOCK (provider);
 613
 614   message = gst_message_new_device_added (GST_OBJECT (provider), device);
 615   gst_bus_post (provider->priv->bus, message);
 616   gst_object_unref (device);
 617 }
 618
 619
 620 /**
 621  * gst_device_provider_device_remove:
 622  * @provider: a #GstDeviceProvider
 623  * @device: a #GstDevice that has been removed
 624  *
 625  * Posts a message on the provider's #GstBus to inform applications that
 626  * a device has been removed.
 627  *
 628  * This is for use by subclasses.
 629  *
 630  * Since: 1.4
 631  */
 632 void
 633 gst_device_provider_device_remove (GstDeviceProvider * provider,
 634     GstDevice * device)
 635 {
 636   GstMessage *message;
 637   GList *item;
 638
 639   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 640   g_return_if_fail (GST_IS_DEVICE (device));
 641
 642   GST_OBJECT_LOCK (provider);
 643   item = g_list_find (provider->devices, device);
 644   if (item) {
 645     provider->devices = g_list_delete_link (provider->devices, item);
 646   }
 647   GST_OBJECT_UNLOCK (provider);
 648
 649   message = gst_message_new_device_removed (GST_OBJECT (provider), device);
 650   g_signal_emit_by_name (device, "removed");
 651   gst_bus_post (provider->priv->bus, message);
 652   if (item)
 653     gst_object_unparent (GST_OBJECT (device));
 654 }
 655
 656 /**
 657  * gst_device_provider_get_hidden_providers:
 658  * @provider: a #GstDeviceProvider
 659  *
 660  * Get the provider factory names of the #GstDeviceProvider instances that
 661  * are hidden by @provider.
 662  *
 663  * Returns: (transfer full) (array zero-terminated=1) (element-type gchar*):
 664  *   a list of hidden providers factory names or %NULL when
 665  *   nothing is hidden by @provider. Free with g_strfreev.
 666  *
 667  * Since: 1.6
 668  */
 669 gchar **
 670 gst_device_provider_get_hidden_providers (GstDeviceProvider * provider)
 671 {
 672   GList *walk;
 673   guint i, len;
 674   gchar **res = NULL;
 675
 676   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
 677
 678   GST_OBJECT_LOCK (provider);
 679   len = g_list_length (provider->priv->hidden_providers);
 680   if (len == 0)
 681     goto done;
 682
 683   res = g_new (gchar *, len + 1);
 684   for (i = 0, walk = provider->priv->hidden_providers; walk;
 685       walk = g_list_next (walk), i++)
 686     res[i] = g_strdup (walk->data);
 687   res[i] = NULL;
 688
 689 done:
 690   GST_OBJECT_UNLOCK (provider);
 691
 692   return res;
 693 }
 694
 695 /**
 696  * gst_device_provider_hide_provider:
 697  * @provider: a #GstDeviceProvider
 698  * @name: a provider factory name
 699  *
 700  * Make @provider hide the devices from the factory with @name.
 701  *
 702  * This function is used when @provider will also provide the devices reported
 703  * by provider factory @name. A monitor should stop monitoring the
 704  * device provider with @name to avoid duplicate devices.
 705  *
 706  * Since: 1.6
 707  */
 708 void
 709 gst_device_provider_hide_provider (GstDeviceProvider * provider,
 710     const gchar * name)
 711 {
 712   GList *find;
 713   const gchar *hidden_name = NULL;
 714
 715   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 716   g_return_if_fail (name != NULL);
 717
 718   GST_OBJECT_LOCK (provider);
 719   find =
 720       g_list_find_custom (provider->priv->hidden_providers, name,
 721       (GCompareFunc) g_strcmp0);
 722   if (find == NULL) {
 723     hidden_name = name;
 724     provider->priv->hidden_providers =
 725         g_list_prepend (provider->priv->hidden_providers, g_strdup (name));
 726   }
 727   GST_OBJECT_UNLOCK (provider);
 728
 729   if (hidden_name)
 730     g_signal_emit (provider, gst_device_provider_signals[PROVIDER_HIDDEN],
 731         0, hidden_name);
 732 }
 733
 734 /**
 735  * gst_device_provider_unhide_provider:
 736  * @provider: a #GstDeviceProvider
 737  * @name: a provider factory name
 738  *
 739  * Make @provider unhide the devices from factory @name.
 740  *
 741  * This function is used when @provider will no longer provide the devices
 742  * reported by provider factory @name. A monitor should start
 743  * monitoring the devices from provider factory @name in order to see
 744  * all devices again.
 745  *
 746  * Since: 1.6
 747  */
 748 void
 749 gst_device_provider_unhide_provider (GstDeviceProvider * provider,
 750     const gchar * name)
 751 {
 752   GList *find;
 753   gchar *unhidden_name = NULL;
 754
 755   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 756   g_return_if_fail (name != NULL);
 757
 758   GST_OBJECT_LOCK (provider);
 759   find =
 760       g_list_find_custom (provider->priv->hidden_providers, name,
 761       (GCompareFunc) g_strcmp0);
 762   if (find) {
 763     unhidden_name = find->data;
 764     provider->priv->hidden_providers =
 765         g_list_delete_link (provider->priv->hidden_providers, find);
 766   }
 767   GST_OBJECT_UNLOCK (provider);
 768
 769   if (unhidden_name) {
 770     g_signal_emit (provider,
 771         gst_device_provider_signals[PROVIDER_UNHIDDEN], 0, unhidden_name);
 772     g_free (unhidden_name);
 773   }
 774 }
 775
 776 /**
 777  * gst_device_provider_device_changed:
 778  * @device: (transfer none): the new version of @changed_device
 779  * @changed_device: (transfer floating): the old version of the device that has been udpated
 780  *
 781  * This function is used when @changed_device was modified into its new form
 782  * @device. This will post a `DEVICE_CHANGED` message on the bus to let
 783  * the application know that the device was modified. #GstDevice is immutable
 784  * for MT. safety purposes so this is an "atomic" way of letting the application
 785  * know when a device was modified.
 786  *
 787  * Since: 1.16
 788  */
 789 void
 790 gst_device_provider_device_changed (GstDeviceProvider * provider,
 791     GstDevice * device, GstDevice * changed_device)
 792 {
 793   GList *dev_lst;
 794   GstMessage *message;
 795
 796   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 797   g_return_if_fail (GST_IS_DEVICE (device));
 798   g_return_if_fail (GST_IS_DEVICE (changed_device));
 799
 800   GST_OBJECT_LOCK (provider);
 801   dev_lst = g_list_find (provider->devices, changed_device);
 802   if (!dev_lst) {
 803     GST_ERROR_OBJECT (provider,
 804         "Trying to update a device we do not have in our own list!");
 805
 806     GST_OBJECT_UNLOCK (provider);
 807     return;
 808   }
 809
 810   if (!gst_object_set_parent (GST_OBJECT (device), GST_OBJECT (provider))) {
 811     GST_OBJECT_UNLOCK (provider);
 812     GST_WARNING_OBJECT (provider, "Could not parent device %p to provider,"
 813         " it already has a parent", device);
 814     return;
 815   }
 816   dev_lst->data = device;
 817   GST_OBJECT_UNLOCK (provider);
 818
 819   message =
 820       gst_message_new_device_changed (GST_OBJECT (provider), device,
 821       changed_device);
 822   gst_bus_post (provider->priv->bus, message);
 823   gst_object_unparent (GST_OBJECT (changed_device));
 824 }