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 (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   g_type_class_add_private (klass, sizeof (GstDevicePrivate));
  86
  87   object_class->get_property = gst_device_get_property;
  88   object_class->set_property = gst_device_set_property;
  89   object_class->finalize = gst_device_finalize;
  90
  91   g_object_class_install_property (object_class, PROP_DISPLAY_NAME,
  92       g_param_spec_string ("display-name", "Display Name",
  93           "The user-friendly name of the device", "",
  94           G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
  95   g_object_class_install_property (object_class, PROP_CAPS,
  96       g_param_spec_boxed ("caps", "Device Caps",
  97           "The possible caps of a device", GST_TYPE_CAPS,
  98           G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
  99   g_object_class_install_property (object_class, PROP_DEVICE_CLASS,
 100       g_param_spec_string ("device-class", "Device Class",
 101           "The Class of the device", "",
 102           G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 103   g_object_class_install_property (object_class, PROP_PROPERTIES,
 104       g_param_spec_boxed ("properties", "Properties",
 105           "The extra properties of the device", GST_TYPE_STRUCTURE,
 106           G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 107
 108   signals[REMOVED] = g_signal_new ("removed", G_TYPE_FROM_CLASS (klass),
 109       G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL, G_TYPE_NONE, 0);
 110 }
 111
 112 static void
 113 gst_device_init (GstDevice * device)
 114 {
 115   device->priv = G_TYPE_INSTANCE_GET_PRIVATE (device, GST_TYPE_DEVICE,
 116       GstDevicePrivate);
 117 }
 118
 119 static void
 120 gst_device_finalize (GObject * object)
 121 {
 122   GstDevice *device = GST_DEVICE (object);
 123
 124   gst_caps_replace (&device->priv->caps, NULL);
 125
 126   if (device->priv->properties)
 127     gst_structure_free (device->priv->properties);
 128   g_free (device->priv->display_name);
 129   g_free (device->priv->device_class);
 130
 131   G_OBJECT_CLASS (gst_device_parent_class)->finalize (object);
 132 }
 133
 134 static void
 135 gst_device_get_property (GObject * object, guint prop_id,
 136     GValue * value, GParamSpec * pspec)
 137 {
 138   GstDevice *gstdevice;
 139
 140   gstdevice = GST_DEVICE_CAST (object);
 141
 142   switch (prop_id) {
 143     case PROP_DISPLAY_NAME:
 144       g_value_take_string (value, gst_device_get_display_name (gstdevice));
 145       break;
 146     case PROP_CAPS:
 147       if (gstdevice->priv->caps)
 148         g_value_take_boxed (value, gst_device_get_caps (gstdevice));
 149       break;
 150     case PROP_DEVICE_CLASS:
 151       g_value_take_string (value, gst_device_get_device_class (gstdevice));
 152       break;
 153     case PROP_PROPERTIES:
 154       if (gstdevice->priv->properties)
 155         g_value_take_boxed (value, gst_device_get_properties (gstdevice));
 156       break;
 157     default:
 158       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 159       break;
 160   }
 161 }
 162
 163
 164 static void
 165 gst_device_set_property (GObject * object, guint prop_id,
 166     const GValue * value, GParamSpec * pspec)
 167 {
 168   GstDevice *gstdevice;
 169
 170   gstdevice = GST_DEVICE_CAST (object);
 171
 172   switch (prop_id) {
 173     case PROP_DISPLAY_NAME:
 174       gstdevice->priv->display_name = g_value_dup_string (value);
 175       break;
 176     case PROP_CAPS:
 177       gst_caps_replace (&gstdevice->priv->caps, g_value_get_boxed (value));
 178       break;
 179     case PROP_DEVICE_CLASS:
 180       gstdevice->priv->device_class = g_value_dup_string (value);
 181       break;
 182     case PROP_PROPERTIES:
 183       if (gstdevice->priv->properties)
 184         gst_structure_free (gstdevice->priv->properties);
 185       gstdevice->priv->properties = g_value_dup_boxed (value);
 186       break;
 187     default:
 188       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 189       break;
 190   }
 191 }
 192
 193 /**
 194  * gst_device_create_element:
 195  * @device: a #GstDevice
 196  * @name: (allow-none): name of new element, or %NULL to automatically
 197  * create a unique name.
 198  *
 199  * Creates the element with all of the required parameters set to use
 200  * this device.
 201  *
 202  * Returns: (transfer full): a new #GstElement configured to use this device
 203  *
 204  * Since: 1.4
 205  */
 206 GstElement *
 207 gst_device_create_element (GstDevice * device, const gchar * name)
 208 {
 209   GstDeviceClass *klass = GST_DEVICE_GET_CLASS (device);
 210
 211   g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
 212
 213   if (klass->create_element)
 214     return klass->create_element (device, name);
 215   else
 216     return NULL;
 217 }
 218
 219 /**
 220  * gst_device_get_caps:
 221  * @device: a #GstDevice
 222  *
 223  * Getter for the #GstCaps that this device supports.
 224  *
 225  * Returns: The #GstCaps supported by this device. Unref with
 226  * gst_caps_unref() when done.
 227  *
 228  * Since: 1.4
 229  */
 230 GstCaps *
 231 gst_device_get_caps (GstDevice * device)
 232 {
 233   g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
 234
 235   if (device->priv->caps)
 236     return gst_caps_ref (device->priv->caps);
 237   else
 238     return NULL;
 239 }
 240
 241 /**
 242  * gst_device_get_display_name:
 243  * @device: a #GstDevice
 244  *
 245  * Gets the user-friendly name of the device.
 246  *
 247  * Returns: The device name. Free with g_free() after use.
 248  *
 249  * Since: 1.4
 250  */
 251 gchar *
 252 gst_device_get_display_name (GstDevice * device)
 253 {
 254   g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
 255
 256   return
 257       g_strdup (device->priv->display_name ? device->priv->display_name : "");
 258 }
 259
 260 /**
 261  * gst_device_get_device_class:
 262  * @device: a #GstDevice
 263  *
 264  * Gets the "class" of a device. This is a "/" separated list of
 265  * classes that represent this device. They are a subset of the
 266  * classes of the #GstDeviceProvider that produced this device.
 267  *
 268  * Returns: The device class. Free with g_free() after use.
 269  *
 270  * Since: 1.4
 271  */
 272 gchar *
 273 gst_device_get_device_class (GstDevice * device)
 274 {
 275   g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
 276
 277   if (device->priv->device_class != NULL)
 278     return g_strdup (device->priv->device_class);
 279   else
 280     return g_strdup ("");
 281 }
 282
 283 /**
 284  * gst_device_get_properties:
 285  * @device: a #GstDevice
 286  *
 287  * Gets the extra properties of a device.
 288  *
 289  * Returns: The extra properties or %NULL when there are none.
 290  *          Free with gst_structure_free() after use.
 291  *
 292  * Since: 1.6
 293  */
 294 GstStructure *
 295 gst_device_get_properties (GstDevice * device)
 296 {
 297   g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
 298
 299   if (device->priv->properties != NULL)
 300     return gst_structure_copy (device->priv->properties);
 301   else
 302     return NULL;
 303 }
 304
 305 /**
 306  * gst_device_reconfigure_element:
 307  * @device: a #GstDevice
 308  * @element: a #GstElement
 309  *
 310  * Tries to reconfigure an existing element to use the device. If this
 311  * function fails, then one must destroy the element and create a new one
 312  * using gst_device_create_element().
 313  *
 314  * Note: This should only be implemented for elements can change their
 315  * device in the PLAYING state.
 316  *
 317  * Returns: %TRUE if the element could be reconfigured to use this device,
 318  * %FALSE otherwise.
 319  *
 320  * Since: 1.4
 321  */
 322 gboolean
 323 gst_device_reconfigure_element (GstDevice * device, GstElement * element)
 324 {
 325   GstDeviceClass *klass = GST_DEVICE_GET_CLASS (device);
 326
 327   g_return_val_if_fail (GST_IS_DEVICE (device), FALSE);
 328
 329   if (klass->reconfigure_element)
 330     return klass->reconfigure_element (device, element);
 331   else
 332     return FALSE;
 333 }
 334
 335 /**
 336  * gst_device_has_classesv:
 337  * @device: a #GstDevice
 338  * @classes: (array zero-terminated=1): a %NULL terminated array of classes
 339  *   to match, only match if all classes are matched
 340  *
 341  * Check if @factory matches all of the given classes
 342  *
 343  * Returns: %TRUE if @device matches.
 344  *
 345  * Since: 1.4
 346  */
 347 gboolean
 348 gst_device_has_classesv (GstDevice * device, gchar ** classes)
 349 {
 350   g_return_val_if_fail (GST_IS_DEVICE (device), FALSE);
 351
 352   if (!classes)
 353     return TRUE;
 354
 355   for (; classes[0]; classes++) {
 356     const gchar *klass = classes[0];
 357     const gchar *found;
 358     guint len;
 359
 360     if (*klass == '\0')
 361       continue;
 362
 363     found = strstr (device->priv->device_class, klass);
 364
 365     if (!found)
 366       return FALSE;
 367     if (found != device->priv->device_class && *(found - 1) != '/')
 368       return FALSE;
 369
 370     len = strlen (klass);
 371     if (found[len] != 0 && found[len] != '/')
 372       return FALSE;
 373   }
 374
 375   return TRUE;
 376 }
 377
 378 /**
 379  * gst_device_has_classes:
 380  * @device: a #GstDevice
 381  * @classes: a "/"-separated list of device classes to match, only match if
 382  *  all classes are matched
 383  *
 384  * Check if @device matches all of the given classes
 385  *
 386  * Returns: %TRUE if @device matches.
 387  *
 388  * Since: 1.4
 389  */
 390 gboolean
 391 gst_device_has_classes (GstDevice * device, const gchar * classes)
 392 {
 393   gchar **classesv;
 394   gboolean res;
 395
 396   g_return_val_if_fail (GST_IS_DEVICE (device), FALSE);
 397
 398   if (!classes)
 399     return TRUE;
 400
 401   classesv = g_strsplit (classes, "/", 0);
 402
 403   res = gst_device_has_classesv (device, classesv);
 404
 405   g_strfreev (classesv);
 406
 407   return res;
 408 }