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