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  * @short_description: A device provider
  25  * @see_also: #GstDevice, #GstDeviceMonitor
  26  *
  27  * A #GstDeviceProvider subclass is provided by a plugin that handles devices
  28  * if there is a way to programatically list connected devices. It can also
  29  * optionally provide updates to the list of connected devices.
  30  *
  31  * Each #GstDeviceProvider subclass is a singleton, a plugin should
  32  * normally provide a single subclass for all devices.
  33  *
  34  * Applications would normally use a #GstDeviceMonitor to monitor devices
  35  * from all relevant providers.
  36  *
  37  * Since: 1.4
  38  */
  39
  40 #ifdef HAVE_CONFIG_H
  41 #include "config.h"
  42 #endif
  43
  44 #include "gst_private.h"
  45
  46 #include "gstdeviceprovider.h"
  47
  48 #include "gstelementmetadata.h"
  49 #include "gstquark.h"
  50
  51 struct _GstDeviceProviderPrivate
  52 {
  53   GstBus *bus;
  54
  55   GMutex start_lock;
  56
  57   gboolean started_count;
  58 };
  59
  60 /* this is used in gstelementfactory.c:gst_element_register() */
  61 GQuark __gst_deviceproviderclass_factory = 0;
  62
  63 static void gst_device_provider_class_init (GstDeviceProviderClass * klass);
  64 static void gst_device_provider_init (GstDeviceProvider * element);
  65 static void gst_device_provider_base_class_init (gpointer g_class);
  66 static void gst_device_provider_base_class_finalize (gpointer g_class);
  67 static void gst_device_provider_dispose (GObject * object);
  68 static void gst_device_provider_finalize (GObject * object);
  69
  70 static gpointer gst_device_provider_parent_class = NULL;
  71
  72 GType
  73 gst_device_provider_get_type (void)
  74 {
  75   static volatile gsize gst_device_provider_type = 0;
  76
  77   if (g_once_init_enter (&gst_device_provider_type)) {
  78     GType _type;
  79     static const GTypeInfo element_info = {
  80       sizeof (GstDeviceProviderClass),
  81       gst_device_provider_base_class_init,
  82       gst_device_provider_base_class_finalize,
  83       (GClassInitFunc) gst_device_provider_class_init,
  84       NULL,
  85       NULL,
  86       sizeof (GstDeviceProvider),
  87       0,
  88       (GInstanceInitFunc) gst_device_provider_init,
  89       NULL
  90     };
  91
  92     _type = g_type_register_static (GST_TYPE_OBJECT, "GstDeviceProvider",
  93         &element_info, G_TYPE_FLAG_ABSTRACT);
  94
  95     __gst_deviceproviderclass_factory =
  96         g_quark_from_static_string ("GST_DEVICEPROVIDERCLASS_FACTORY");
  97     g_once_init_leave (&gst_device_provider_type, _type);
  98   }
  99   return gst_device_provider_type;
 100 }
 101
 102 static void
 103 gst_device_provider_base_class_init (gpointer g_class)
 104 {
 105   GstDeviceProviderClass *klass = GST_DEVICE_PROVIDER_CLASS (g_class);
 106
 107   /* Copy the element details here so elements can inherit the
 108    * details from their base class and classes only need to set
 109    * the details in class_init instead of base_init */
 110   klass->metadata =
 111       klass->metadata ? gst_structure_copy (klass->metadata) :
 112       gst_structure_new_empty ("metadata");
 113
 114   klass->factory = g_type_get_qdata (G_TYPE_FROM_CLASS (klass),
 115       __gst_deviceproviderclass_factory);
 116 }
 117
 118 static void
 119 gst_device_provider_base_class_finalize (gpointer g_class)
 120 {
 121   GstDeviceProviderClass *klass = GST_DEVICE_PROVIDER_CLASS (g_class);
 122
 123   gst_structure_free (klass->metadata);
 124 }
 125
 126 static void
 127 gst_device_provider_class_init (GstDeviceProviderClass * klass)
 128 {
 129   GObjectClass *gobject_class = (GObjectClass *) klass;
 130
 131   gst_device_provider_parent_class = g_type_class_peek_parent (klass);
 132
 133   g_type_class_add_private (klass, sizeof (GstDeviceProviderPrivate));
 134
 135   gobject_class->dispose = gst_device_provider_dispose;
 136   gobject_class->finalize = gst_device_provider_finalize;
 137 }
 138
 139 static void
 140 gst_device_provider_init (GstDeviceProvider * provider)
 141 {
 142   provider->priv = G_TYPE_INSTANCE_GET_PRIVATE (provider,
 143       GST_TYPE_DEVICE_PROVIDER, GstDeviceProviderPrivate);
 144
 145   g_mutex_init (&provider->priv->start_lock);
 146
 147   provider->priv->bus = gst_bus_new ();
 148   gst_bus_set_flushing (provider->priv->bus, TRUE);
 149 }
 150
 151
 152 static void
 153 gst_device_provider_dispose (GObject * object)
 154 {
 155   GstDeviceProvider *provider = GST_DEVICE_PROVIDER (object);
 156
 157   gst_object_replace ((GstObject **) & provider->priv->bus, NULL);
 158
 159   GST_OBJECT_LOCK (provider);
 160   g_list_free_full (provider->devices, (GDestroyNotify) gst_object_unparent);
 161   provider->devices = NULL;
 162   GST_OBJECT_UNLOCK (provider);
 163
 164   G_OBJECT_CLASS (gst_device_provider_parent_class)->dispose (object);
 165 }
 166
 167 static void
 168 gst_device_provider_finalize (GObject * object)
 169 {
 170   GstDeviceProvider *provider = GST_DEVICE_PROVIDER (object);
 171
 172   g_mutex_clear (&provider->priv->start_lock);
 173
 174   G_OBJECT_CLASS (gst_device_provider_parent_class)->finalize (object);
 175 }
 176
 177 /**
 178  * gst_device_provider_class_add_metadata:
 179  * @klass: class to set metadata for
 180  * @key: the key to set
 181  * @value: the value to set
 182  *
 183  * Set @key with @value as metadata in @klass.
 184  *
 185  * Since: 1.4
 186  */
 187 void
 188 gst_device_provider_class_add_metadata (GstDeviceProviderClass * klass,
 189     const gchar * key, const gchar * value)
 190 {
 191   g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
 192   g_return_if_fail (key != NULL);
 193   g_return_if_fail (value != NULL);
 194
 195   gst_structure_set ((GstStructure *) klass->metadata,
 196       key, G_TYPE_STRING, value, NULL);
 197 }
 198
 199 /**
 200  * gst_device_provider_class_add_static_metadata:
 201  * @klass: class to set metadata for
 202  * @key: the key to set
 203  * @value: (transfer full): the value to set
 204  *
 205  * Set @key with @value as metadata in @klass.
 206  *
 207  * Same as gst_device_provider_class_add_metadata(), but @value must be a static string
 208  * or an inlined string, as it will not be copied. (GStreamer plugins will
 209  * be made resident once loaded, so this function can be used even from
 210  * dynamically loaded plugins.)
 211  *
 212  * Since: 1.4
 213  */
 214 void
 215 gst_device_provider_class_add_static_metadata (GstDeviceProviderClass * klass,
 216     const gchar * key, const gchar * value)
 217 {
 218   GValue val = G_VALUE_INIT;
 219
 220   g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
 221   g_return_if_fail (key != NULL);
 222   g_return_if_fail (value != NULL);
 223
 224   g_value_init (&val, G_TYPE_STRING);
 225   g_value_set_static_string (&val, value);
 226   gst_structure_take_value ((GstStructure *) klass->metadata, key, &val);
 227 }
 228
 229 /**
 230  * gst_device_provider_class_set_metadata:
 231  * @klass: class to set metadata for
 232  * @longname: The long English name of the device provider. E.g. "File Sink"
 233  * @classification: String describing the type of device provider, as an
 234  *  unordered list separated with slashes ('/'). See draft-klass.txt of the
 235  *  design docs
 236  * for more details and common types. E.g: "Sink/File"
 237  * @description: Sentence describing the purpose of the device provider.
 238  * E.g: "Write stream to a file"
 239  * @author: Name and contact details of the author(s). Use \n to separate
 240  * multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
 241  *
 242  * Sets the detailed information for a #GstDeviceProviderClass.
 243  * <note>This function is for use in _class_init functions only.</note>
 244  *
 245  * Since: 1.4
 246  */
 247 void
 248 gst_device_provider_class_set_metadata (GstDeviceProviderClass * klass,
 249     const gchar * longname, const gchar * classification,
 250     const gchar * description, const gchar * author)
 251 {
 252   g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
 253   g_return_if_fail (longname != NULL && *longname != '\0');
 254   g_return_if_fail (classification != NULL && *classification != '\0');
 255   g_return_if_fail (description != NULL && *description != '\0');
 256   g_return_if_fail (author != NULL && *author != '\0');
 257
 258   gst_structure_id_set ((GstStructure *) klass->metadata,
 259       GST_QUARK (ELEMENT_METADATA_LONGNAME), G_TYPE_STRING, longname,
 260       GST_QUARK (ELEMENT_METADATA_KLASS), G_TYPE_STRING, classification,
 261       GST_QUARK (ELEMENT_METADATA_DESCRIPTION), G_TYPE_STRING, description,
 262       GST_QUARK (ELEMENT_METADATA_AUTHOR), G_TYPE_STRING, author, NULL);
 263 }
 264
 265 /**
 266  * gst_device_provider_class_set_static_metadata:
 267  * @klass: class to set metadata for
 268  * @longname: (transfer full): The long English name of the element. E.g. "File Sink"
 269  * @classification: (transfer full): String describing the type of element, as
 270  * an unordered list separated with slashes ('/'). See draft-klass.txt of the
 271  * design docs for more details and common types. E.g: "Sink/File"
 272  * @description: (transfer full): Sentence describing the purpose of the
 273  * element.  E.g: "Write stream to a file"
 274  * @author: (transfer full): Name and contact details of the author(s). Use \n
 275  * to separate multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at
 276  * foo.com&gt;"
 277  *
 278  * Sets the detailed information for a #GstDeviceProviderClass.
 279  * <note>This function is for use in _class_init functions only.</note>
 280  *
 281  * Same as gst_device_provider_class_set_metadata(), but @longname, @classification,
 282  * @description, and @author must be static strings or inlined strings, as
 283  * they will not be copied. (GStreamer plugins will be made resident once
 284  * loaded, so this function can be used even from dynamically loaded plugins.)
 285  *
 286  * Since: 1.4
 287  */
 288 void
 289 gst_device_provider_class_set_static_metadata (GstDeviceProviderClass * klass,
 290     const gchar * longname, const gchar * classification,
 291     const gchar * description, const gchar * author)
 292 {
 293   GstStructure *s = (GstStructure *) klass->metadata;
 294   GValue val = G_VALUE_INIT;
 295
 296   g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
 297   g_return_if_fail (longname != NULL && *longname != '\0');
 298   g_return_if_fail (classification != NULL && *classification != '\0');
 299   g_return_if_fail (description != NULL && *description != '\0');
 300   g_return_if_fail (author != NULL && *author != '\0');
 301
 302   g_value_init (&val, G_TYPE_STRING);
 303
 304   g_value_set_static_string (&val, longname);
 305   gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_LONGNAME), &val);
 306
 307   g_value_set_static_string (&val, classification);
 308   gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_KLASS), &val);
 309
 310   g_value_set_static_string (&val, description);
 311   gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_DESCRIPTION),
 312       &val);
 313
 314   g_value_set_static_string (&val, author);
 315   gst_structure_id_take_value (s, GST_QUARK (ELEMENT_METADATA_AUTHOR), &val);
 316 }
 317
 318 /**
 319  * gst_device_provider_class_get_metadata:
 320  * @klass: class to get metadata for
 321  * @key: the key to get
 322  *
 323  * Get metadata with @key in @klass.
 324  *
 325  * Returns: the metadata for @key.
 326  *
 327  * Since: 1.4
 328  */
 329 const gchar *
 330 gst_device_provider_class_get_metadata (GstDeviceProviderClass * klass,
 331     const gchar * key)
 332 {
 333   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass), NULL);
 334   g_return_val_if_fail (key != NULL, NULL);
 335
 336   return gst_structure_get_string ((GstStructure *) klass->metadata, key);
 337 }
 338
 339 /**
 340  * gst_device_provider_get_devices:
 341  * @provider: A #GstDeviceProvider
 342  *
 343  * Gets a list of devices that this provider understands. This may actually
 344  * probe the hardware if the provider is not currently started.
 345  *
 346  * Returns: (transfer full) (element-type GstDevice): a #GList of
 347  *   #GstDevice
 348  *
 349  * Since: 1.4
 350  */
 351
 352 GList *
 353 gst_device_provider_get_devices (GstDeviceProvider * provider)
 354 {
 355   GstDeviceProviderClass *klass;
 356   GList *devices = NULL;
 357   gboolean started;
 358   GList *item;
 359
 360   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
 361   klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
 362
 363   g_mutex_lock (&provider->priv->start_lock);
 364   started = (provider->priv->started_count > 0);
 365
 366   if (started) {
 367     GST_OBJECT_LOCK (provider);
 368     for (item = provider->devices; item; item = item->next)
 369       devices = g_list_prepend (devices, gst_object_ref (item->data));
 370     GST_OBJECT_UNLOCK (provider);
 371   } else if (klass->probe)
 372     devices = klass->probe (provider);
 373
 374   g_mutex_unlock (&provider->priv->start_lock);
 375
 376   return devices;
 377 }
 378
 379 /**
 380  * gst_device_provider_start:
 381  * @provider: A #GstDeviceProvider
 382  *
 383  * Starts providering the devices. This will cause #GST_MESSAGE_DEVICE_ADDED
 384  * and #GST_MESSAGE_DEVICE_REMOVED messages to be posted on the provider's bus
 385  * when devices are added or removed from the system.
 386  *
 387  * Since the #GstDeviceProvider is a singleton,
 388  * gst_device_provider_start() may already have been called by another
 389  * user of the object, gst_device_provider_stop() needs to be called the same
 390  * number of times.
 391  *
 392  * Returns: %TRUE if the device providering could be started
 393  *
 394  * Since: 1.4
 395  */
 396
 397 gboolean
 398 gst_device_provider_start (GstDeviceProvider * provider)
 399 {
 400   GstDeviceProviderClass *klass;
 401   gboolean ret = FALSE;
 402
 403   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), FALSE);
 404   klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
 405
 406   g_mutex_lock (&provider->priv->start_lock);
 407
 408   if (provider->priv->started_count > 0) {
 409     ret = TRUE;
 410     goto started;
 411   }
 412
 413   if (klass->start)
 414     ret = klass->start (provider);
 415
 416   if (ret) {
 417     provider->priv->started_count++;
 418     gst_bus_set_flushing (provider->priv->bus, FALSE);
 419   }
 420
 421 started:
 422
 423   g_mutex_unlock (&provider->priv->start_lock);
 424
 425   return ret;
 426 }
 427
 428 /**
 429  * gst_device_provider_stop:
 430  * @provider: A #GstDeviceProvider
 431  *
 432  * Decreases the use-count by one. If the use count reaches zero, this
 433  * #GstDeviceProvider will stop providering the devices. This needs to be
 434  * called the same number of times that gst_device_provider_start() was called.
 435  *
 436  * Since: 1.4
 437  */
 438
 439 void
 440 gst_device_provider_stop (GstDeviceProvider * provider)
 441 {
 442   GstDeviceProviderClass *klass;
 443
 444   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 445   klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
 446
 447   g_mutex_lock (&provider->priv->start_lock);
 448
 449   if (provider->priv->started_count == 1) {
 450     gst_bus_set_flushing (provider->priv->bus, TRUE);
 451     if (klass->stop)
 452       klass->stop (provider);
 453     GST_OBJECT_LOCK (provider);
 454     g_list_free_full (provider->devices, (GDestroyNotify) gst_object_unparent);
 455     provider->devices = NULL;
 456     GST_OBJECT_UNLOCK (provider);
 457   } else if (provider->priv->started_count < 1) {
 458     g_critical
 459         ("Trying to stop a GstDeviceProvider %s which is already stopped",
 460         GST_OBJECT_NAME (provider));
 461   }
 462
 463   provider->priv->started_count--;
 464   g_mutex_unlock (&provider->priv->start_lock);
 465 }
 466
 467
 468 /**
 469  * gst_device_provider_get_factory:
 470  * @provider: a #GstDeviceProvider to request the device provider factory of.
 471  *
 472  * Retrieves the factory that was used to create this device provider.
 473  *
 474  * Returns: (transfer none): the #GstDeviceProviderFactory used for
 475  *     creating this device provider. no refcounting is needed.
 476  *
 477  * Since: 1.4
 478  */
 479 GstDeviceProviderFactory *
 480 gst_device_provider_get_factory (GstDeviceProvider * provider)
 481 {
 482   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
 483
 484   return GST_DEVICE_PROVIDER_GET_CLASS (provider)->factory;
 485 }
 486
 487 /**
 488  * gst_device_provider_can_provider:
 489  * @provider: a #GstDeviceProvider
 490  *
 491  * If this function returns %TRUE, then the device provider can provider if
 492  * devices are added or removed. Otherwise, it can only do static probing.
 493  *
 494  * Returns: %TRUE if the #GstDeviceProvider support providering, %FALSE otherwise
 495  */
 496 gboolean
 497 gst_device_provider_can_monitor (GstDeviceProvider * provider)
 498 {
 499   GstDeviceProviderClass *klass;
 500
 501   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), FALSE);
 502   klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
 503
 504   if (klass->start)
 505     return TRUE;
 506   else
 507     return FALSE;
 508 }
 509
 510 /**
 511  * gst_device_provider_get_bus:
 512  * @provider: a #GstDeviceProvider
 513  *
 514  * Gets the #GstBus of this #GstDeviceProvider
 515  *
 516  * Returns: (transfer full): a #GstBus
 517  *
 518  * Since: 1.4
 519  */
 520 GstBus *
 521 gst_device_provider_get_bus (GstDeviceProvider * provider)
 522 {
 523   g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
 524
 525   return gst_object_ref (provider->priv->bus);
 526 }
 527
 528 /**
 529  * gst_device_provider_device_add:
 530  * @provider: a #GstDeviceProvider
 531  * @device: (transfer full): a #GstDevice that has been added
 532  *
 533  * Posts a message on the provider's #GstBus to inform applications that
 534  * a new device has been added.
 535  *
 536  * This is for use by subclasses.
 537  *
 538  * Since: 1.4
 539  */
 540 void
 541 gst_device_provider_device_add (GstDeviceProvider * provider,
 542     GstDevice * device)
 543 {
 544   GstMessage *message;
 545
 546   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 547   g_return_if_fail (GST_IS_DEVICE (device));
 548
 549   if (!gst_object_set_parent (GST_OBJECT (device), GST_OBJECT (provider))) {
 550     GST_WARNING_OBJECT (provider, "Could not parent device %p to provider,"
 551         " it already has a parent", device);
 552     return;
 553   }
 554
 555   GST_OBJECT_LOCK (provider);
 556   provider->devices = g_list_prepend (provider->devices,
 557       gst_object_ref (device));
 558   GST_OBJECT_UNLOCK (provider);
 559
 560   message = gst_message_new_device_added (GST_OBJECT (provider), device);
 561   gst_bus_post (provider->priv->bus, message);
 562   gst_object_unref (device);
 563 }
 564
 565
 566 /**
 567  * gst_device_provider_device_remove:
 568  * @provider: a #GstDeviceProvider
 569  * @device: a #GstDevice that has been removed
 570  *
 571  * Posts a message on the provider's #GstBus to inform applications that
 572  * a device has been removed.
 573  *
 574  * This is for use by subclasses.
 575  *
 576  * Since: 1.4
 577  */
 578 void
 579 gst_device_provider_device_remove (GstDeviceProvider * provider,
 580     GstDevice * device)
 581 {
 582   GstMessage *message;
 583   GList *item;
 584
 585   g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
 586   g_return_if_fail (GST_IS_DEVICE (device));
 587
 588   GST_OBJECT_LOCK (provider);
 589   item = g_list_find (provider->devices, device);
 590   if (item) {
 591     provider->devices = g_list_delete_link (provider->devices, item);
 592   }
 593   GST_OBJECT_UNLOCK (provider);
 594
 595   message = gst_message_new_device_removed (GST_OBJECT (provider), device);
 596   g_signal_emit_by_name (device, "removed");
 597   gst_bus_post (provider->priv->bus, message);
 598   if (item)
 599     gst_object_unparent (GST_OBJECT (device));
 600 }