subprojects/gstreamer/gst/gstdevice.c

   1 /* GStreamer
   2  * Copyright (C) 2012 Olivier Crete <olivier.crete@collabora.com>
   3  *
   4  * gstdevice.c: Device discovery
   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:gstdevice
  24  * @title: GstDevice
  25  * @short_description: Object representing a device
  26  * @see_also: #GstDeviceProvider
  27  *
  28  * #GstDevice are objects representing a device, they contain
  29  * relevant metadata about the device, such as its class and the #GstCaps
  30  * representing the media types it can produce or handle.
  31  *
  32  * #GstDevice are created by #GstDeviceProvider objects which can be
  33  * aggregated by #GstDeviceMonitor objects.
  34  *
  35  * Since: 1.4
  36  */
  37
  38 #ifdef HAVE_CONFIG_H
  39 #include "config.h"
  40 #endif
  41
  42 #include "gst_private.h"
  43
  44 #include "gstdevice.h"
  45
  46 enum
  47 {
  48   PROP_DISPLAY_NAME = 1,
  49   PROP_CAPS,
  50   PROP_DEVICE_CLASS,
  51   PROP_PROPERTIES
  52 };
  53
  54 enum
  55 {
  56   REMOVED,
  57   LAST_SIGNAL
  58 };
  59
  60 struct _GstDevicePrivate
  61 {
  62   GstCaps *caps;
  63   gchar *device_class;
  64   gchar *display_name;
  65   GstStructure *properties;
  66 };
  67
  68
  69 static guint signals[LAST_SIGNAL];
  70
  71 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GstDevice, gst_device, GST_TYPE_OBJECT);
  72
  73 static void gst_device_get_property (GObject * object, guint property_id,
  74     GValue * value, GParamSpec * pspec);
  75 static void gst_device_set_property (GObject * object, guint property_id,
  76     const GValue * value, GParamSpec * pspec);
  77 static void gst_device_finalize (GObject * object);
  78
  79
  80 static void
  81 gst_device_class_init (GstDeviceClass * klass)
  82 {
  83   GObjectClass *object_class = G_OBJECT_CLASS (klass);
  84
  85   object_class->get_property = gst_device_get_property;
  86   object_class->set_property = gst_device_set_property;
  87   object_class->finalize = gst_device_finalize;
  88
  89   g_object_class_install_property (object_class, PROP_DISPLAY_NAME,
  90       g_param_spec_string ("display-name", "Display Name",
  91           "The user-friendly name of the device", "",
  92           G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
  93   g_object_class_install_property (object_class, PROP_CAPS,
  94       g_param_spec_boxed ("caps", "Device Caps",
  95           "The possible caps of a device", GST_TYPE_CAPS,
  96           G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
  97   g_object_class_install_property (object_class, PROP_DEVICE_CLASS,
  98       g_param_spec_string ("device-class", "Device Class",
  99           "The Class of the device", "",
 100           G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 101   g_object_class_install_property (object_class, PROP_PROPERTIES,
 102       g_param_spec_boxed ("properties", "Properties",
 103           "The extra properties of the device", GST_TYPE_STRUCTURE,
 104           G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 105
 106   signals[REMOVED] = g_signal_new ("removed", G_TYPE_FROM_CLASS (klass),
 107       G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL, G_TYPE_NONE, 0);
 108 }
 109
 110 static void
 111 gst_device_init (GstDevice * device)
 112 {
 113   device->priv = gst_device_get_instance_private (device);
 114 }
 115
 116 static void
 117 gst_device_finalize (GObject * object)
 118 {
 119   GstDevice *device = GST_DEVICE (object);
 120
 121   gst_caps_replace (&device->priv->caps, NULL);
 122
 123   if (device->priv->properties)
 124     gst_structure_free (device->priv->properties);
 125   g_free (device->priv->display_name);
 126   g_free (device->priv->device_class);
 127
 128   G_OBJECT_CLASS (gst_device_parent_class)->finalize (object);
 129 }
 130
 131 static void
 132 gst_device_get_property (GObject * object, guint prop_id,
 133     GValue * value, GParamSpec * pspec)
 134 {
 135   GstDevice *gstdevice;
 136
 137   gstdevice = GST_DEVICE_CAST (object);
 138
 139   switch (prop_id) {
 140     case PROP_DISPLAY_NAME:
 141       g_value_take_string (value, gst_device_get_display_name (gstdevice));
 142       break;
 143     case PROP_CAPS:
 144       if (gstdevice->priv->caps)
 145         g_value_take_boxed (value, gst_device_get_caps (gstdevice));
 146       break;
 147     case PROP_DEVICE_CLASS:
 148       g_value_take_string (value, gst_device_get_device_class (gstdevice));
 149       break;
 150     case PROP_PROPERTIES:
 151       if (gstdevice->priv->properties)
 152         g_value_take_boxed (value, gst_device_get_properties (gstdevice));
 153       break;
 154     default:
 155       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 156       break;
 157   }
 158 }
 159
 160
 161 static void
 162 gst_device_set_property (GObject * object, guint prop_id,
 163     const GValue * value, GParamSpec * pspec)
 164 {
 165   GstDevice *gstdevice;
 166
 167   gstdevice = GST_DEVICE_CAST (object);
 168
 169   switch (prop_id) {
 170     case PROP_DISPLAY_NAME:
 171       gstdevice->priv->display_name = g_value_dup_string (value);
 172       break;
 173     case PROP_CAPS:
 174       gst_caps_replace (&gstdevice->priv->caps, g_value_get_boxed (value));
 175       break;
 176     case PROP_DEVICE_CLASS:
 177       gstdevice->priv->device_class = g_value_dup_string (value);
 178       break;
 179     case PROP_PROPERTIES:
 180       if (gstdevice->priv->properties)
 181         gst_structure_free (gstdevice->priv->properties);
 182       gstdevice->priv->properties = g_value_dup_boxed (value);
 183       break;
 184     default:
 185       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 186       break;
 187   }
 188 }
 189
 190 /**
 191  * gst_device_create_element:
 192  * @device: a #GstDevice
 193  * @name: (allow-none): name of new element, or %NULL to automatically
 194  * create a unique name.
 195  *
 196  * Creates the element with all of the required parameters set to use
 197  * this device.
 198  *
 199  * Returns: (transfer floating) (nullable): a new #GstElement configured to use
 200  * this device
 201  *
 202  * Since: 1.4
 203  */
 204 GstElement *
 205 gst_device_create_element (GstDevice * device, const gchar * name)
 206 {
 207   GstDeviceClass *klass = GST_DEVICE_GET_CLASS (device);
 208   GstElement *element = NULL;
 209
 210   g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
 211
 212   if (klass->create_element)
 213     element = klass->create_element (device, name);
 214
 215   if (element && !g_object_is_floating ((GObject *) element)) {
 216     /* The reference we receive here should be floating, but we can't force
 217      * it at our level. Simply raise a critical to make the issue obvious to bindings
 218      * developers */
 219     g_critical ("The created element should be floating, "
 220         "this is probably caused by faulty bindings");
 221   }
 222
 223   return element;
 224 }
 225
 226 /**
 227  * gst_device_get_caps:
 228  * @device: a #GstDevice
 229  *
 230  * Getter for the #GstCaps that this device supports.
 231  *
 232  * Returns: (nullable): The #GstCaps supported by this device. Unref with
 233  * gst_caps_unref() when done.
 234  *
 235  * Since: 1.4
 236  */
 237 GstCaps *
 238 gst_device_get_caps (GstDevice * device)
 239 {
 240   g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
 241
 242   if (device->priv->caps)
 243     return gst_caps_ref (device->priv->caps);
 244   else
 245     return NULL;
 246 }
 247
 248 /**
 249  * gst_device_get_display_name:
 250  * @device: a #GstDevice
 251  *
 252  * Gets the user-friendly name of the device.
 253  *
 254  * Returns: The device name. Free with g_free() after use.
 255  *
 256  * Since: 1.4
 257  */
 258 gchar *
 259 gst_device_get_display_name (GstDevice * device)
 260 {
 261   g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
 262
 263   return
 264       g_strdup (device->priv->display_name ? device->priv->display_name : "");
 265 }
 266
 267 /**
 268  * gst_device_get_device_class:
 269  * @device: a #GstDevice
 270  *
 271  * Gets the "class" of a device. This is a "/" separated list of
 272  * classes that represent this device. They are a subset of the
 273  * classes of the #GstDeviceProvider that produced this device.
 274  *
 275  * Returns: The device class. Free with g_free() after use.
 276  *
 277  * Since: 1.4
 278  */
 279 gchar *
 280 gst_device_get_device_class (GstDevice * device)
 281 {
 282   g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
 283
 284   if (device->priv->device_class != NULL)
 285     return g_strdup (device->priv->device_class);
 286   else
 287     return g_strdup ("");
 288 }
 289
 290 /**
 291  * gst_device_get_properties:
 292  * @device: a #GstDevice
 293  *
 294  * Gets the extra properties of a device.
 295  *
 296  * Returns: (nullable): The extra properties or %NULL when there are none.
 297  *          Free with gst_structure_free() after use.
 298  *
 299  * Since: 1.6
 300  */
 301 GstStructure *
 302 gst_device_get_properties (GstDevice * device)
 303 {
 304   g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
 305
 306   if (device->priv->properties != NULL)
 307     return gst_structure_copy (device->priv->properties);
 308   else
 309     return NULL;
 310 }
 311
 312 /**
 313  * gst_device_reconfigure_element:
 314  * @device: a #GstDevice
 315  * @element: a #GstElement
 316  *
 317  * Tries to reconfigure an existing element to use the device. If this
 318  * function fails, then one must destroy the element and create a new one
 319  * using gst_device_create_element().
 320  *
 321  * Note: This should only be implemented for elements can change their
 322  * device in the PLAYING state.
 323  *
 324  * Returns: %TRUE if the element could be reconfigured to use this device,
 325  * %FALSE otherwise.
 326  *
 327  * Since: 1.4
 328  */
 329 gboolean
 330 gst_device_reconfigure_element (GstDevice * device, GstElement * element)
 331 {
 332   GstDeviceClass *klass = GST_DEVICE_GET_CLASS (device);
 333
 334   g_return_val_if_fail (GST_IS_DEVICE (device), FALSE);
 335
 336   if (klass->reconfigure_element)
 337     return klass->reconfigure_element (device, element);
 338   else
 339     return FALSE;
 340 }
 341
 342 /**
 343  * gst_device_has_classesv:
 344  * @device: a #GstDevice
 345  * @classes: (array zero-terminated=1): a %NULL terminated array of classes
 346  *   to match, only match if all classes are matched
 347  *
 348  * Check if @factory matches all of the given classes
 349  *
 350  * Returns: %TRUE if @device matches.
 351  *
 352  * Since: 1.4
 353  */
 354 gboolean
 355 gst_device_has_classesv (GstDevice * device, gchar ** classes)
 356 {
 357   g_return_val_if_fail (GST_IS_DEVICE (device), FALSE);
 358
 359   if (!classes)
 360     return TRUE;
 361
 362   for (; classes[0]; classes++) {
 363     const gchar *klass = classes[0];
 364     const gchar *found;
 365     guint len;
 366
 367     if (*klass == '\0')
 368       continue;
 369
 370     found = strstr (device->priv->device_class, klass);
 371
 372     if (!found)
 373       return FALSE;
 374     if (found != device->priv->device_class && *(found - 1) != '/')
 375       return FALSE;
 376
 377     len = strlen (klass);
 378     if (found[len] != 0 && found[len] != '/')
 379       return FALSE;
 380   }
 381
 382   return TRUE;
 383 }
 384
 385 /**
 386  * gst_device_has_classes:
 387  * @device: a #GstDevice
 388  * @classes: a "/"-separated list of device classes to match, only match if
 389  *  all classes are matched
 390  *
 391  * Check if @device matches all of the given classes
 392  *
 393  * Returns: %TRUE if @device matches.
 394  *
 395  * Since: 1.4
 396  */
 397 gboolean
 398 gst_device_has_classes (GstDevice * device, const gchar * classes)
 399 {
 400   gchar **classesv;
 401   gboolean res;
 402
 403   g_return_val_if_fail (GST_IS_DEVICE (device), FALSE);
 404
 405   if (!classes)
 406     return TRUE;
 407
 408   classesv = g_strsplit (classes, "/", 0);
 409
 410   res = gst_device_has_classesv (device, classesv);
 411
 412   g_strfreev (classesv);
 413
 414   return res;
 415 }