subprojects/gstreamer/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   gint 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 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, NULL, NULL, G_TYPE_NONE, 1, G_TYPE_STRING);
 155
 156   gst_device_provider_signals[PROVIDER_UNHIDDEN] =
 157       g_signal_new ("provider-unhidden", G_TYPE_FROM_CLASS (klass),
 158       G_SIGNAL_RUN_FIRST, 0, NULL, NULL, NULL, G_TYPE_NONE, 1, G_TYPE_STRING);
 159 }
 160
 161 static void
 162 gst_device_provider_init (GstDeviceProvider * provider)
 163 {
 164   provider->priv = gst_device_provider_get_instance_private (provider);
 165
 166   g_mutex_init (&provider->priv->start_lock);
 167
 168   provider->priv->started_count = 0;
 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  * If the provider has been started, this will returned the same #GstDevice
 395  * objedcts that have been returned by the #GST_MESSAGE_DEVICE_ADDED messages.
 396  *
 397  * Returns: (transfer full) (element-type GstDevice): a #GList of
 398  *   #GstDevice
 399  *
 400  * Since: 1.4
 401  */
 402
 403 GList *
 404 gst_device_provider_get_devices (GstDeviceProvider * provider)
 405 {
 406   GstDeviceProviderClass *klass;
 407   GList *devices = NULL;
 408   gboolean started;
 409   GList *item;
 410
 411   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
 412   klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
 413
 414   g_mutex_lock (&provider->priv->start_lock);
 415   started = (provider->priv->started_count > 0);
 416
 417   if (started) {
 418     GST_OBJECT_LOCK (provider);
 419     for (item = provider->devices; item; item = item->next)
 420       devices = g_list_prepend (devices, gst_object_ref (item->data));
 421     GST_OBJECT_UNLOCK (provider);
 422   } else if (klass->probe) {
 423
 424     devices = klass->probe (provider);
 425
 426     for (item = devices; item; item = item->next)
 427       if (g_object_is_floating (item->data))
 428         g_object_ref_sink (item->data);
 429   }
 430
 431   g_mutex_unlock (&provider->priv->start_lock);
 432
 433   return devices;
 434 }
 435
 436 /**
 437  * gst_device_provider_start:
 438  * @provider: A #GstDeviceProvider
 439  *
 440  * Starts providering the devices. This will cause #GST_MESSAGE_DEVICE_ADDED
 441  * and #GST_MESSAGE_DEVICE_REMOVED messages to be posted on the provider's bus
 442  * when devices are added or removed from the system.
 443  *
 444  * Since the #GstDeviceProvider is a singleton,
 445  * gst_device_provider_start() may already have been called by another
 446  * user of the object, gst_device_provider_stop() needs to be called the same
 447  * number of times.
 448  *
 449  * After this function has been called, gst_device_provider_get_devices() will
 450  * return the same objects that have been received from the
 451  * #GST_MESSAGE_DEVICE_ADDED messages and will no longer probe.
 452  *
 453  * Returns: %TRUE if the device providering could be started
 454  *
 455  * Since: 1.4
 456  */
 457
 458 gboolean
 459 gst_device_provider_start (GstDeviceProvider * provider)
 460 {
 461   GstDeviceProviderClass *klass;
 462   gboolean ret = FALSE;
 463
 464   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), FALSE);
 465   klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
 466
 467   g_mutex_lock (&provider->priv->start_lock);
 468
 469   if (provider->priv->started_count > 0) {
 470     provider->priv->started_count++;
 471     ret = TRUE;
 472     goto started;
 473   }
 474
 475   gst_bus_set_flushing (provider->priv->bus, FALSE);
 476
 477   if (klass->start) {
 478     ret = klass->start (provider);
 479   } else {
 480     GList *devices = NULL, *item;
 481
 482     devices = klass->probe (provider);
 483
 484     for (item = devices; item; item = item->next) {
 485       GstDevice *device = GST_DEVICE (item->data);
 486       gboolean was_floating = g_object_is_floating (item->data);
 487
 488       gst_device_provider_device_add (provider, device);
 489
 490       if (!was_floating)
 491         g_object_unref (item->data);
 492     }
 493
 494     g_list_free (devices);
 495
 496     ret = TRUE;
 497   }
 498
 499   if (ret) {
 500     provider->priv->started_count++;
 501   } else if (provider->priv->started_count == 0) {
 502     gst_bus_set_flushing (provider->priv->bus, TRUE);
 503   }
 504
 505 started:
 506
 507   g_mutex_unlock (&provider->priv->start_lock);
 508
 509   return ret;
 510 }
 511
 512 /**
 513  * gst_device_provider_stop:
 514  * @provider: A #GstDeviceProvider
 515  *
 516  * Decreases the use-count by one. If the use count reaches zero, this
 517  * #GstDeviceProvider will stop providering the devices. This needs to be
 518  * called the same number of times that gst_device_provider_start() was called.
 519  *
 520  * Since: 1.4
 521  */
 522
 523 void
 524 gst_device_provider_stop (GstDeviceProvider * provider)
 525 {
 526   GstDeviceProviderClass *klass;
 527
 528   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 529   klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
 530
 531   g_mutex_lock (&provider->priv->start_lock);
 532
 533   if (provider->priv->started_count == 1) {
 534     gst_bus_set_flushing (provider->priv->bus, TRUE);
 535     if (klass->stop)
 536       klass->stop (provider);
 537     GST_OBJECT_LOCK (provider);
 538     g_list_free_full (provider->devices, (GDestroyNotify) gst_object_unparent);
 539     provider->devices = NULL;
 540     GST_OBJECT_UNLOCK (provider);
 541   } else if (provider->priv->started_count < 1) {
 542     g_critical
 543         ("Trying to stop a GstDeviceProvider %s which is already stopped",
 544         GST_OBJECT_NAME (provider));
 545   }
 546
 547   provider->priv->started_count--;
 548   g_mutex_unlock (&provider->priv->start_lock);
 549 }
 550
 551 /**
 552  * gst_device_provider_get_factory:
 553  * @provider: a #GstDeviceProvider to request the device provider factory of.
 554  *
 555  * Retrieves the factory that was used to create this device provider.
 556  *
 557  * Returns: (transfer none) (nullable): the #GstDeviceProviderFactory used for
 558  *     creating this device provider. no refcounting is needed.
 559  *
 560  * Since: 1.4
 561  */
 562 GstDeviceProviderFactory *
 563 gst_device_provider_get_factory (GstDeviceProvider * provider)
 564 {
 565   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
 566
 567   return GST_DEVICE_PROVIDER_GET_CLASS (provider)->factory;
 568 }
 569
 570 /**
 571  * gst_device_provider_can_provider:
 572  * @provider: a #GstDeviceProvider
 573  *
 574  * If this function returns %TRUE, then the device provider can provider if
 575  * devices are added or removed. Otherwise, it can only do static probing.
 576  *
 577  * Returns: %TRUE if the #GstDeviceProvider support providering, %FALSE otherwise
 578  */
 579 gboolean
 580 gst_device_provider_can_monitor (GstDeviceProvider * provider)
 581 {
 582   GstDeviceProviderClass *klass;
 583
 584   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), FALSE);
 585   klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
 586
 587   if (klass->start)
 588     return TRUE;
 589   else
 590     return FALSE;
 591 }
 592
 593 /**
 594  * gst_device_provider_get_bus:
 595  * @provider: a #GstDeviceProvider
 596  *
 597  * Gets the #GstBus of this #GstDeviceProvider
 598  *
 599  * Returns: (transfer full): a #GstBus
 600  *
 601  * Since: 1.4
 602  */
 603 GstBus *
 604 gst_device_provider_get_bus (GstDeviceProvider * provider)
 605 {
 606   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
 607
 608   return gst_object_ref (provider->priv->bus);
 609 }
 610
 611 /**
 612  * gst_device_provider_device_add:
 613  * @provider: a #GstDeviceProvider
 614  * @device: (transfer floating): a #GstDevice that has been added
 615  *
 616  * Posts a message on the provider's #GstBus to inform applications that
 617  * a new device has been added.
 618  *
 619  * This is for use by subclasses.
 620  *
 621  * @device's reference count will be incremented, and any floating reference
 622  * will be removed (see gst_object_ref_sink()).
 623  *
 624  * Since: 1.4
 625  */
 626 void
 627 gst_device_provider_device_add (GstDeviceProvider * provider,
 628     GstDevice * device)
 629 {
 630   GstMessage *message;
 631
 632   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 633   g_return_if_fail (GST_IS_DEVICE (device));
 634
 635   if (!gst_object_set_parent (GST_OBJECT (device), GST_OBJECT (provider))) {
 636     GST_WARNING_OBJECT (provider, "Could not parent device %p to provider,"
 637         " it already has a parent", device);
 638     return;
 639   }
 640
 641   GST_OBJECT_LOCK (provider);
 642   /* Take an additional reference so we can be sure nobody removed it from the
 643    * provider in the meantime and we can safely emit the message */
 644   gst_object_ref (device);
 645   provider->devices = g_list_prepend (provider->devices, device);
 646   GST_OBJECT_UNLOCK (provider);
 647
 648   message = gst_message_new_device_added (GST_OBJECT (provider), device);
 649   gst_bus_post (provider->priv->bus, message);
 650   gst_object_unref (device);
 651 }
 652
 653
 654 /**
 655  * gst_device_provider_device_remove:
 656  * @provider: a #GstDeviceProvider
 657  * @device: a #GstDevice that has been removed
 658  *
 659  * Posts a message on the provider's #GstBus to inform applications that
 660  * a device has been removed.
 661  *
 662  * This is for use by subclasses.
 663  *
 664  * Since: 1.4
 665  */
 666 void
 667 gst_device_provider_device_remove (GstDeviceProvider * provider,
 668     GstDevice * device)
 669 {
 670   GstMessage *message;
 671   GList *item;
 672
 673   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 674   g_return_if_fail (GST_IS_DEVICE (device));
 675
 676   GST_OBJECT_LOCK (provider);
 677   item = g_list_find (provider->devices, device);
 678   if (item) {
 679     provider->devices = g_list_delete_link (provider->devices, item);
 680   }
 681   GST_OBJECT_UNLOCK (provider);
 682
 683   message = gst_message_new_device_removed (GST_OBJECT (provider), device);
 684   g_signal_emit_by_name (device, "removed");
 685   gst_bus_post (provider->priv->bus, message);
 686   if (item)
 687     gst_object_unparent (GST_OBJECT (device));
 688 }
 689
 690 /**
 691  * gst_device_provider_get_hidden_providers:
 692  * @provider: a #GstDeviceProvider
 693  *
 694  * Get the provider factory names of the #GstDeviceProvider instances that
 695  * are hidden by @provider.
 696  *
 697  * Returns: (transfer full) (array zero-terminated=1) (element-type gchar*):
 698  *   a list of hidden providers factory names or %NULL when
 699  *   nothing is hidden by @provider. Free with g_strfreev.
 700  *
 701  * Since: 1.6
 702  */
 703 gchar **
 704 gst_device_provider_get_hidden_providers (GstDeviceProvider * provider)
 705 {
 706   GList *walk;
 707   guint i, len;
 708   gchar **res = NULL;
 709
 710   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
 711
 712   GST_OBJECT_LOCK (provider);
 713   len = g_list_length (provider->priv->hidden_providers);
 714   if (len == 0)
 715     goto done;
 716
 717   res = g_new (gchar *, len + 1);
 718   for (i = 0, walk = provider->priv->hidden_providers; walk;
 719       walk = g_list_next (walk), i++)
 720     res[i] = g_strdup (walk->data);
 721   res[i] = NULL;
 722
 723 done:
 724   GST_OBJECT_UNLOCK (provider);
 725
 726   return res;
 727 }
 728
 729 /**
 730  * gst_device_provider_hide_provider:
 731  * @provider: a #GstDeviceProvider
 732  * @name: a provider factory name
 733  *
 734  * Make @provider hide the devices from the factory with @name.
 735  *
 736  * This function is used when @provider will also provide the devices reported
 737  * by provider factory @name. A monitor should stop monitoring the
 738  * device provider with @name to avoid duplicate devices.
 739  *
 740  * Since: 1.6
 741  */
 742 void
 743 gst_device_provider_hide_provider (GstDeviceProvider * provider,
 744     const gchar * name)
 745 {
 746   GList *find;
 747   const gchar *hidden_name = NULL;
 748
 749   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 750   g_return_if_fail (name != NULL);
 751
 752   GST_OBJECT_LOCK (provider);
 753   find =
 754       g_list_find_custom (provider->priv->hidden_providers, name,
 755       (GCompareFunc) g_strcmp0);
 756   if (find == NULL) {
 757     hidden_name = name;
 758     provider->priv->hidden_providers =
 759         g_list_prepend (provider->priv->hidden_providers, g_strdup (name));
 760   }
 761   GST_OBJECT_UNLOCK (provider);
 762
 763   if (hidden_name)
 764     g_signal_emit (provider, gst_device_provider_signals[PROVIDER_HIDDEN],
 765         0, hidden_name);
 766 }
 767
 768 /**
 769  * gst_device_provider_unhide_provider:
 770  * @provider: a #GstDeviceProvider
 771  * @name: a provider factory name
 772  *
 773  * Make @provider unhide the devices from factory @name.
 774  *
 775  * This function is used when @provider will no longer provide the devices
 776  * reported by provider factory @name. A monitor should start
 777  * monitoring the devices from provider factory @name in order to see
 778  * all devices again.
 779  *
 780  * Since: 1.6
 781  */
 782 void
 783 gst_device_provider_unhide_provider (GstDeviceProvider * provider,
 784     const gchar * name)
 785 {
 786   GList *find;
 787   gchar *unhidden_name = NULL;
 788
 789   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 790   g_return_if_fail (name != NULL);
 791
 792   GST_OBJECT_LOCK (provider);
 793   find =
 794       g_list_find_custom (provider->priv->hidden_providers, name,
 795       (GCompareFunc) g_strcmp0);
 796   if (find) {
 797     unhidden_name = find->data;
 798     provider->priv->hidden_providers =
 799         g_list_delete_link (provider->priv->hidden_providers, find);
 800   }
 801   GST_OBJECT_UNLOCK (provider);
 802
 803   if (unhidden_name) {
 804     g_signal_emit (provider,
 805         gst_device_provider_signals[PROVIDER_UNHIDDEN], 0, unhidden_name);
 806     g_free (unhidden_name);
 807   }
 808 }
 809
 810 /**
 811  * gst_device_provider_device_changed:
 812  * @device: (transfer none): the new version of @changed_device
 813  * @changed_device: (transfer floating): the old version of the device that has been updated
 814  *
 815  * This function is used when @changed_device was modified into its new form
 816  * @device. This will post a `DEVICE_CHANGED` message on the bus to let
 817  * the application know that the device was modified. #GstDevice is immutable
 818  * for MT. safety purposes so this is an "atomic" way of letting the application
 819  * know when a device was modified.
 820  *
 821  * Since: 1.16
 822  */
 823 void
 824 gst_device_provider_device_changed (GstDeviceProvider * provider,
 825     GstDevice * device, GstDevice * changed_device)
 826 {
 827   GList *dev_lst;
 828   GstMessage *message;
 829
 830   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 831   g_return_if_fail (GST_IS_DEVICE (device));
 832   g_return_if_fail (GST_IS_DEVICE (changed_device));
 833
 834   GST_OBJECT_LOCK (provider);
 835   dev_lst = g_list_find (provider->devices, changed_device);
 836   if (!dev_lst) {
 837     GST_ERROR_OBJECT (provider,
 838         "Trying to update a device we do not have in our own list!");
 839
 840     GST_OBJECT_UNLOCK (provider);
 841     return;
 842   }
 843
 844   if (!gst_object_set_parent (GST_OBJECT (device), GST_OBJECT (provider))) {
 845     GST_OBJECT_UNLOCK (provider);
 846     GST_WARNING_OBJECT (provider, "Could not parent device %p to provider,"
 847         " it already has a parent", device);
 848     return;
 849   }
 850   dev_lst->data = device;
 851   GST_OBJECT_UNLOCK (provider);
 852
 853   message =
 854       gst_message_new_device_changed (GST_OBJECT (provider), device,
 855       changed_device);
 856   gst_bus_post (provider->priv->bus, message);
 857   gst_object_unparent (GST_OBJECT (changed_device));
 858 }
 859
 860 /**
 861  * gst_device_provider_is_started:
 862  * @provider: a #GstDeviceProvider
 863  *
 864  * This function can be used to know if the @provider was successfully started.
 865  *
 866  * Since: 1.20
 867  */
 868 gboolean
 869 gst_device_provider_is_started (GstDeviceProvider * provider)
 870 {
 871   gboolean started = FALSE;
 872
 873   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), FALSE);
 874
 875   g_mutex_lock (&provider->priv->start_lock);
 876   started = provider->priv->started_count > 0;
 877   g_mutex_unlock (&provider->priv->start_lock);
 878   return started;
 879 }