2 * Copyright (C) 2012 Olivier Crete <olivier.crete@collabora.com>
4 * gstdeviceprovider.c: Device probing and monitoring
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
23 * SECTION:gstdeviceprovider
24 * @short_description: A device provider
25 * @see_also: #GstDevice, #GstGlobalDeviceMonitor
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.
31 * Each #GstDeviceProvider subclass is a singleton, a plugin should
32 * normally provide a single subclass for all devices.
34 * Applications would normally use a #GstGlobalDeviceMonitor to monitor devices
35 * from all relevant providers.
44 #include "gst_private.h"
46 #include "gstdeviceprovider.h"
48 #include "gstelementmetadata.h"
51 struct _GstDeviceProviderPrivate
57 gboolean started_count;
60 /* this is used in gstelementfactory.c:gst_element_register() */
61 GQuark __gst_deviceproviderclass_factory = 0;
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);
70 static gpointer gst_device_provider_parent_class = NULL;
73 gst_device_provider_get_type (void)
75 static volatile gsize gst_device_provider_type = 0;
77 if (g_once_init_enter (&gst_device_provider_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,
86 sizeof (GstDeviceProvider),
88 (GInstanceInitFunc) gst_device_provider_init,
92 _type = g_type_register_static (GST_TYPE_OBJECT, "GstDeviceProvider",
93 &element_info, G_TYPE_FLAG_ABSTRACT);
95 __gst_deviceproviderclass_factory =
96 g_quark_from_static_string ("GST_DEVICEPROVIDERCLASS_FACTORY");
97 g_once_init_leave (&gst_device_provider_type, _type);
99 return gst_device_provider_type;
103 gst_device_provider_base_class_init (gpointer g_class)
105 GstDeviceProviderClass *klass = GST_DEVICE_PROVIDER_CLASS (g_class);
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 */
111 klass->metadata ? gst_structure_copy (klass->metadata) :
112 gst_structure_new_empty ("metadata");
114 klass->factory = g_type_get_qdata (G_TYPE_FROM_CLASS (klass),
115 __gst_deviceproviderclass_factory);
119 gst_device_provider_base_class_finalize (gpointer g_class)
121 GstDeviceProviderClass *klass = GST_DEVICE_PROVIDER_CLASS (g_class);
123 gst_structure_free (klass->metadata);
127 gst_device_provider_class_init (GstDeviceProviderClass * klass)
129 GObjectClass *gobject_class = (GObjectClass *) klass;
131 gst_device_provider_parent_class = g_type_class_peek_parent (klass);
133 g_type_class_add_private (klass, sizeof (GstDeviceProviderPrivate));
135 gobject_class->dispose = gst_device_provider_dispose;
136 gobject_class->finalize = gst_device_provider_finalize;
140 gst_device_provider_init (GstDeviceProvider * provider)
142 provider->priv = G_TYPE_INSTANCE_GET_PRIVATE (provider,
143 GST_TYPE_DEVICE_PROVIDER, GstDeviceProviderPrivate);
145 g_mutex_init (&provider->priv->start_lock);
147 provider->priv->bus = gst_bus_new ();
148 gst_bus_set_flushing (provider->priv->bus, TRUE);
153 gst_device_provider_dispose (GObject * object)
155 GstDeviceProvider *provider = GST_DEVICE_PROVIDER (object);
157 gst_object_replace ((GstObject **) & provider->priv->bus, NULL);
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);
164 G_OBJECT_CLASS (gst_device_provider_parent_class)->dispose (object);
168 gst_device_provider_finalize (GObject * object)
170 GstDeviceProvider *provider = GST_DEVICE_PROVIDER (object);
172 g_mutex_clear (&provider->priv->start_lock);
174 G_OBJECT_CLASS (gst_device_provider_parent_class)->finalize (object);
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
183 * Set @key with @value as metadata in @klass.
186 gst_device_provider_class_add_metadata (GstDeviceProviderClass * klass,
187 const gchar * key, const gchar * value)
189 g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
190 g_return_if_fail (key != NULL);
191 g_return_if_fail (value != NULL);
193 gst_structure_set ((GstStructure *) klass->metadata,
194 key, G_TYPE_STRING, value, NULL);
198 * gst_device_provider_class_add_static_metadata:
199 * @klass: class to set metadata for
200 * @key: the key to set
201 * @value: the value to set
203 * Set @key with @value as metadata in @klass.
205 * Same as gst_device_provider_class_add_metadata(), but @value must be a static string
206 * or an inlined string, as it will not be copied. (GStreamer plugins will
207 * be made resident once loaded, so this function can be used even from
208 * dynamically loaded plugins.)
213 gst_device_provider_class_add_static_metadata (GstDeviceProviderClass * klass,
214 const gchar * key, const gchar * value)
216 GValue val = G_VALUE_INIT;
218 g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
219 g_return_if_fail (key != NULL);
220 g_return_if_fail (value != NULL);
222 g_value_init (&val, G_TYPE_STRING);
223 g_value_set_static_string (&val, value);
224 gst_structure_take_value ((GstStructure *) klass->metadata, key, &val);
228 * gst_device_provider_class_set_metadata:
229 * @klass: class to set metadata for
230 * @longname: The long English name of the device provider. E.g. "File Sink"
231 * @classification: String describing the type of device provider, as an
232 * unordered list separated with slashes ('/'). See draft-klass.txt of the
234 * for more details and common types. E.g: "Sink/File"
235 * @description: Sentence describing the purpose of the device provider.
236 * E.g: "Write stream to a file"
237 * @author: Name and contact details of the author(s). Use \n to separate
238 * multiple author metadata. E.g: "Joe Bloggs <joe.blogs at foo.com>"
240 * Sets the detailed information for a #GstDeviceProviderClass.
241 * <note>This function is for use in _class_init functions only.</note>
246 gst_device_provider_class_set_metadata (GstDeviceProviderClass * klass,
247 const gchar * longname, const gchar * classification,
248 const gchar * description, const gchar * author)
250 g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
251 g_return_if_fail (longname != NULL && *longname != '\0');
252 g_return_if_fail (classification != NULL && *classification != '\0');
253 g_return_if_fail (description != NULL && *description != '\0');
254 g_return_if_fail (author != NULL && *author != '\0');
256 gst_structure_id_set ((GstStructure *) klass->metadata,
257 GST_QUARK (ELEMENT_METADATA_LONGNAME), G_TYPE_STRING, longname,
258 GST_QUARK (ELEMENT_METADATA_KLASS), G_TYPE_STRING, classification,
259 GST_QUARK (ELEMENT_METADATA_DESCRIPTION), G_TYPE_STRING, description,
260 GST_QUARK (ELEMENT_METADATA_AUTHOR), G_TYPE_STRING, author, NULL);
264 * gst_device_provider_class_set_static_metadata:
265 * @klass: class to set metadata for
266 * @longname: The long English name of the element. E.g. "File Sink"
267 * @classification: String describing the type of element, as an unordered list
268 * separated with slashes ('/'). See draft-klass.txt of the design docs
269 * for more details and common types. E.g: "Sink/File"
270 * @description: Sentence describing the purpose of the element.
271 * E.g: "Write stream to a file"
272 * @author: Name and contact details of the author(s). Use \n to separate
273 * multiple author metadata. E.g: "Joe Bloggs <joe.blogs at foo.com>"
275 * Sets the detailed information for a #GstDeviceProviderClass.
276 * <note>This function is for use in _class_init functions only.</note>
278 * Same as gst_device_provider_class_set_metadata(), but @longname, @classification,
279 * @description, and @author must be static strings or inlined strings, as
280 * they will not be copied. (GStreamer plugins will be made resident once
281 * loaded, so this function can be used even from dynamically loaded plugins.)
286 gst_device_provider_class_set_static_metadata (GstDeviceProviderClass * klass,
287 const gchar * longname, const gchar * classification,
288 const gchar * description, const gchar * author)
290 GstStructure *s = (GstStructure *) klass->metadata;
291 GValue val = G_VALUE_INIT;
293 g_return_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass));
294 g_return_if_fail (longname != NULL && *longname != '\0');
295 g_return_if_fail (classification != NULL && *classification != '\0');
296 g_return_if_fail (description != NULL && *description != '\0');
297 g_return_if_fail (author != NULL && *author != '\0');
299 g_value_init (&val, G_TYPE_STRING);
301 g_value_set_static_string (&val, longname);
302 gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_LONGNAME), &val);
304 g_value_set_static_string (&val, classification);
305 gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_KLASS), &val);
307 g_value_set_static_string (&val, description);
308 gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_DESCRIPTION),
311 g_value_set_static_string (&val, author);
312 gst_structure_id_take_value (s, GST_QUARK (ELEMENT_METADATA_AUTHOR), &val);
316 * gst_device_provider_class_get_metadata:
317 * @klass: class to get metadata for
318 * @key: the key to get
320 * Get metadata with @key in @klass.
322 * Returns: the metadata for @key.
327 gst_device_provider_class_get_metadata (GstDeviceProviderClass * klass,
330 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER_CLASS (klass), NULL);
331 g_return_val_if_fail (key != NULL, NULL);
333 return gst_structure_get_string ((GstStructure *) klass->metadata, key);
337 * gst_device_provider_get_devices:
338 * @provider: A #GstDeviceProvider
340 * Gets a list of devices that this provider understands. This may actually
341 * probe the hardware if the provider is not currently started.
343 * Returns: (transfer full) (element-type GstDevice): a #GList of
350 gst_device_provider_get_devices (GstDeviceProvider * provider)
352 GstDeviceProviderClass *klass;
353 GList *devices = NULL;
357 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
358 klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
360 g_mutex_lock (&provider->priv->start_lock);
361 started = (provider->priv->started_count > 0);
364 GST_OBJECT_LOCK (provider);
365 for (item = provider->devices; item; item = item->next)
366 devices = g_list_prepend (devices, gst_object_ref (item->data));
367 GST_OBJECT_UNLOCK (provider);
368 } else if (klass->probe)
369 devices = klass->probe (provider);
371 g_mutex_unlock (&provider->priv->start_lock);
377 * gst_device_provider_start:
378 * @provider: A #GstDeviceProvider
380 * Starts providering the devices. This will cause #GST_MESSAGE_DEVICE messages
381 * to be posted on the provider's bus when devices are added or removed from
384 * Since the #GstDeviceProvider is a singleton,
385 * gst_device_provider_start() may already have been called by another
386 * user of the object, gst_device_provider_stop() needs to be called the same
389 * Returns: %TRUE if the device providering could be started
395 gst_device_provider_start (GstDeviceProvider * provider)
397 GstDeviceProviderClass *klass;
398 gboolean ret = FALSE;
400 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), FALSE);
401 klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
403 g_mutex_lock (&provider->priv->start_lock);
405 if (provider->priv->started_count > 0) {
411 ret = klass->start (provider);
414 provider->priv->started_count++;
415 gst_bus_set_flushing (provider->priv->bus, FALSE);
420 g_mutex_unlock (&provider->priv->start_lock);
426 * gst_device_provider_stop:
427 * @provider: A #GstDeviceProvider
429 * Decreases the use-count by one. If the use count reaches zero, this
430 * #GstDeviceProvider will stop providering the devices. This needs to be
431 * called the same number of times that gst_device_provider_start() was called.
437 gst_device_provider_stop (GstDeviceProvider * provider)
439 GstDeviceProviderClass *klass;
441 g_return_if_fail (GST_IS_DEVICE_PROVIDER (provider));
442 klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
444 g_mutex_lock (&provider->priv->start_lock);
446 if (provider->priv->started_count == 1) {
447 gst_bus_set_flushing (provider->priv->bus, TRUE);
449 klass->stop (provider);
450 GST_OBJECT_LOCK (provider);
451 g_list_free_full (provider->devices, (GDestroyNotify) gst_object_unparent);
452 provider->devices = NULL;
453 GST_OBJECT_UNLOCK (provider);
454 } else if (provider->priv->started_count < 1) {
456 ("Trying to stop a GstDeviceProvider %s which is already stopped",
457 GST_OBJECT_NAME (provider));
460 provider->priv->started_count--;
461 g_mutex_unlock (&provider->priv->start_lock);
466 * gst_device_provider_get_factory:
467 * @provider: a #GstDeviceProvider to request the device provider factory of.
469 * Retrieves the factory that was used to create this device provider.
471 * Returns: (transfer none): the #GstDeviceProviderFactory used for
472 * creating this device provider. no refcounting is needed.
476 GstDeviceProviderFactory *
477 gst_device_provider_get_factory (GstDeviceProvider * provider)
479 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
481 return GST_DEVICE_PROVIDER_GET_CLASS (provider)->factory;
485 * gst_device_provider_can_provider:
486 * @provider: a #GstDeviceProvider
488 * If this function returns %TRUE, then the device provider can provider if
489 * devices are added or removed. Otherwise, it can only do static probing.
491 * Returns: %TRUE if the #GstDeviceProvider support providering, %FALSE otherwise
494 gst_device_provider_can_monitor (GstDeviceProvider * provider)
496 GstDeviceProviderClass *klass;
498 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), FALSE);
499 klass = GST_DEVICE_PROVIDER_GET_CLASS (provider);
508 * gst_device_provider_get_bus:
509 * @provider: a #GstDeviceProvider
511 * Gets the #GstBus of this #GstDeviceProvider
513 * Returns: (transfer full): a #GstBus
518 gst_device_provider_get_bus (GstDeviceProvider * provider)
520 g_return_val_if_fail (GST_IS_DEVICE_PROVIDER (provider), NULL);
522 return gst_object_ref (provider->priv->bus);
526 * gst_device_provider_device_add:
527 * @provider: a #GstDeviceProvider
528 * @device: (transfer full): a #GstDevice that has been added
530 * Posts a message on the provider's #GstBus to inform applications that
531 * a new device has been added.
533 * This is for use by subclasses.
538 gst_device_provider_device_add (GstDeviceProvider * provider,
543 if (!gst_object_set_parent (GST_OBJECT (device), GST_OBJECT (provider))) {
544 GST_WARNING_OBJECT (provider, "Could not parent device %p to provider,"
545 " it already has a parent", device);
549 GST_OBJECT_LOCK (provider);
550 provider->devices = g_list_prepend (provider->devices,
551 gst_object_ref (device));
552 GST_OBJECT_UNLOCK (provider);
554 message = gst_message_new_device_added (GST_OBJECT (provider), device);
555 gst_bus_post (provider->priv->bus, message);
556 gst_object_unref (device);
561 * gst_device_provider_device_remove:
562 * @provider: a #GstDeviceProvider
563 * @device: a #GstDevice that has been removed
565 * Posts a message on the provider's #GstBus to inform applications that
566 * a device has been removed.
568 * This is for use by subclasses.
573 gst_device_provider_device_remove (GstDeviceProvider * provider,
579 GST_OBJECT_LOCK (provider);
580 item = g_list_find (provider->devices, device);
582 provider->devices = g_list_delete_link (provider->devices, item);
584 GST_OBJECT_UNLOCK (provider);
586 message = gst_message_new_device_removed (GST_OBJECT (provider), device);
587 g_signal_emit_by_name (device, "removed");
588 gst_bus_post (provider->priv->bus, message);
590 gst_object_unparent (GST_OBJECT (device));