gstdevice.c 10.4 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
/* GStreamer
 * Copyright (C) 2012 Olivier Crete <olivier.crete@collabora.com>
 *
 * gstdevice.c: Device discovery
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

22 23
/**
 * SECTION:gstdevice
24
 * @title: GstDevice
25
 * @short_description: Object representing a device
26
 * @see_also: #GstDeviceProvider
27 28 29 30 31
 *
 * #GstDevice are objects representing a device, they contain
 * relevant metadata about the device, such as its class and the #GstCaps
 * representing the media types it can produce or handle.
 *
32
 * #GstDevice are created by #GstDeviceProvider objects which can be
33
 * aggregated by #GstDeviceMonitor objects.
34 35 36 37
 *
 * Since: 1.4
 */

38 39 40 41
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

42
#include "gst_private.h"
43

44
#include "gstdevice.h"
45 46 47 48

enum
{
  PROP_DISPLAY_NAME = 1,
49
  PROP_CAPS,
50 51
  PROP_DEVICE_CLASS,
  PROP_PROPERTIES
52 53 54 55 56 57 58 59 60 61 62
};

enum
{
  REMOVED,
  LAST_SIGNAL
};

struct _GstDevicePrivate
{
  GstCaps *caps;
63
  gchar *device_class;
64
  gchar *display_name;
65
  GstStructure *properties;
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98
};


static guint signals[LAST_SIGNAL];

G_DEFINE_ABSTRACT_TYPE (GstDevice, gst_device, GST_TYPE_OBJECT);

static void gst_device_get_property (GObject * object, guint property_id,
    GValue * value, GParamSpec * pspec);
static void gst_device_set_property (GObject * object, guint property_id,
    const GValue * value, GParamSpec * pspec);
static void gst_device_finalize (GObject * object);


static void
gst_device_class_init (GstDeviceClass * klass)
{
  GObjectClass *object_class = G_OBJECT_CLASS (klass);

  g_type_class_add_private (klass, sizeof (GstDevicePrivate));

  object_class->get_property = gst_device_get_property;
  object_class->set_property = gst_device_set_property;
  object_class->finalize = gst_device_finalize;

  g_object_class_install_property (object_class, PROP_DISPLAY_NAME,
      g_param_spec_string ("display-name", "Display Name",
          "The user-friendly name of the device", "",
          G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
  g_object_class_install_property (object_class, PROP_CAPS,
      g_param_spec_boxed ("caps", "Device Caps",
          "The possible caps of a device", GST_TYPE_CAPS,
          G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
99 100
  g_object_class_install_property (object_class, PROP_DEVICE_CLASS,
      g_param_spec_string ("device-class", "Device Class",
101 102
          "The Class of the device", "",
          G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
103 104 105 106
  g_object_class_install_property (object_class, PROP_PROPERTIES,
      g_param_spec_boxed ("properties", "Properties",
          "The extra properties of the device", GST_TYPE_STRUCTURE,
          G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125

  signals[REMOVED] = g_signal_new ("removed", G_TYPE_FROM_CLASS (klass),
      G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL, G_TYPE_NONE, 0);
}

static void
gst_device_init (GstDevice * device)
{
  device->priv = G_TYPE_INSTANCE_GET_PRIVATE (device, GST_TYPE_DEVICE,
      GstDevicePrivate);
}

static void
gst_device_finalize (GObject * object)
{
  GstDevice *device = GST_DEVICE (object);

  gst_caps_replace (&device->priv->caps, NULL);

126 127
  if (device->priv->properties)
    gst_structure_free (device->priv->properties);
128
  g_free (device->priv->display_name);
129
  g_free (device->priv->device_class);
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149

  G_OBJECT_CLASS (gst_device_parent_class)->finalize (object);
}

static void
gst_device_get_property (GObject * object, guint prop_id,
    GValue * value, GParamSpec * pspec)
{
  GstDevice *gstdevice;

  gstdevice = GST_DEVICE_CAST (object);

  switch (prop_id) {
    case PROP_DISPLAY_NAME:
      g_value_take_string (value, gst_device_get_display_name (gstdevice));
      break;
    case PROP_CAPS:
      if (gstdevice->priv->caps)
        g_value_take_boxed (value, gst_device_get_caps (gstdevice));
      break;
150 151
    case PROP_DEVICE_CLASS:
      g_value_take_string (value, gst_device_get_device_class (gstdevice));
152
      break;
153 154 155 156
    case PROP_PROPERTIES:
      if (gstdevice->priv->properties)
        g_value_take_boxed (value, gst_device_get_properties (gstdevice));
      break;
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
      break;
  }
}


static void
gst_device_set_property (GObject * object, guint prop_id,
    const GValue * value, GParamSpec * pspec)
{
  GstDevice *gstdevice;

  gstdevice = GST_DEVICE_CAST (object);

  switch (prop_id) {
    case PROP_DISPLAY_NAME:
      gstdevice->priv->display_name = g_value_dup_string (value);
      break;
    case PROP_CAPS:
      gst_caps_replace (&gstdevice->priv->caps, g_value_get_boxed (value));
      break;
179 180
    case PROP_DEVICE_CLASS:
      gstdevice->priv->device_class = g_value_dup_string (value);
181
      break;
182 183 184 185 186
    case PROP_PROPERTIES:
      if (gstdevice->priv->properties)
        gst_structure_free (gstdevice->priv->properties);
      gstdevice->priv->properties = g_value_dup_boxed (value);
      break;
187 188 189 190 191 192 193 194 195
    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
      break;
  }
}

/**
 * gst_device_create_element:
 * @device: a #GstDevice
196
 * @name: (allow-none): name of new element, or %NULL to automatically
197 198
 * create a unique name.
 *
Sebastian Dröge's avatar
Sebastian Dröge committed
199
 * Creates the element with all of the required parameters set to use
200 201
 * this device.
 *
202 203 204 205 206 207 208 209 210
 * Returns: (transfer full): a new #GstElement configured to use this device
 *
 * Since: 1.4
 */
GstElement *
gst_device_create_element (GstDevice * device, const gchar * name)
{
  GstDeviceClass *klass = GST_DEVICE_GET_CLASS (device);

Olivier Crête's avatar
Olivier Crête committed
211 212
  g_return_val_if_fail (GST_IS_DEVICE (device), NULL);

213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232
  if (klass->create_element)
    return klass->create_element (device, name);
  else
    return NULL;
}

/**
 * gst_device_get_caps:
 * @device: a #GstDevice
 *
 * Getter for the #GstCaps that this device supports.
 *
 * Returns: The #GstCaps supported by this device. Unref with
 * gst_caps_unref() when done.
 *
 * Since: 1.4
 */
GstCaps *
gst_device_get_caps (GstDevice * device)
{
Olivier Crête's avatar
Olivier Crête committed
233 234
  g_return_val_if_fail (GST_IS_DEVICE (device), NULL);

235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253
  if (device->priv->caps)
    return gst_caps_ref (device->priv->caps);
  else
    return NULL;
}

/**
 * gst_device_get_display_name:
 * @device: a #GstDevice
 *
 * Gets the user-friendly name of the device.
 *
 * Returns: The device name. Free with g_free() after use.
 *
 * Since: 1.4
 */
gchar *
gst_device_get_display_name (GstDevice * device)
{
Olivier Crête's avatar
Olivier Crête committed
254 255
  g_return_val_if_fail (GST_IS_DEVICE (device), NULL);

256 257 258 259 260
  return
      g_strdup (device->priv->display_name ? device->priv->display_name : "");
}

/**
261
 * gst_device_get_device_class:
262 263 264 265
 * @device: a #GstDevice
 *
 * Gets the "class" of a device. This is a "/" separated list of
 * classes that represent this device. They are a subset of the
266
 * classes of the #GstDeviceProvider that produced this device.
267 268 269 270 271 272
 *
 * Returns: The device class. Free with g_free() after use.
 *
 * Since: 1.4
 */
gchar *
273
gst_device_get_device_class (GstDevice * device)
274
{
Olivier Crête's avatar
Olivier Crête committed
275 276
  g_return_val_if_fail (GST_IS_DEVICE (device), NULL);

277 278 279 280
  if (device->priv->device_class != NULL)
    return g_strdup (device->priv->device_class);
  else
    return g_strdup ("");
281 282
}

283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304
/**
 * gst_device_get_properties:
 * @device: a #GstDevice
 *
 * Gets the extra properties of a device.
 *
 * Returns: The extra properties or %NULL when there are none.
 *          Free with gst_structure_free() after use.
 *
 * Since: 1.6
 */
GstStructure *
gst_device_get_properties (GstDevice * device)
{
  g_return_val_if_fail (GST_IS_DEVICE (device), NULL);

  if (device->priv->properties != NULL)
    return gst_structure_copy (device->priv->properties);
  else
    return NULL;
}

305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
/**
 * gst_device_reconfigure_element:
 * @device: a #GstDevice
 * @element: a #GstElement
 *
 * Tries to reconfigure an existing element to use the device. If this
 * function fails, then one must destroy the element and create a new one
 * using gst_device_create_element().
 *
 * Note: This should only be implemented for elements can change their
 * device in the PLAYING state.
 *
 * Returns: %TRUE if the element could be reconfigured to use this device,
 * %FALSE otherwise.
 *
 * Since: 1.4
 */
gboolean
gst_device_reconfigure_element (GstDevice * device, GstElement * element)
{
  GstDeviceClass *klass = GST_DEVICE_GET_CLASS (device);

Olivier Crête's avatar
Olivier Crête committed
327 328
  g_return_val_if_fail (GST_IS_DEVICE (device), FALSE);

329 330 331 332 333
  if (klass->reconfigure_element)
    return klass->reconfigure_element (device, element);
  else
    return FALSE;
}
334 335 336 337

/**
 * gst_device_has_classesv:
 * @device: a #GstDevice
338 339
 * @classes: (array zero-terminated=1): a %NULL terminated array of classes
 *   to match, only match if all classes are matched
340 341 342 343 344 345 346 347 348 349 350 351
 *
 * Check if @factory matches all of the given classes
 *
 * Returns: %TRUE if @device matches.
 *
 * Since: 1.4
 */
gboolean
gst_device_has_classesv (GstDevice * device, gchar ** classes)
{
  g_return_val_if_fail (GST_IS_DEVICE (device), FALSE);

Olivier Crête's avatar
Olivier Crête committed
352 353
  if (!classes)
    return TRUE;
354 355

  for (; classes[0]; classes++) {
356
    const gchar *klass = classes[0];
357 358 359
    const gchar *found;
    guint len;

360
    if (*klass == '\0')
361 362
      continue;

363
    found = strstr (device->priv->device_class, klass);
364 365 366

    if (!found)
      return FALSE;
367
    if (found != device->priv->device_class && *(found - 1) != '/')
368 369
      return FALSE;

370
    len = strlen (klass);
371 372 373 374 375 376 377 378 379 380
    if (found[len] != 0 && found[len] != '/')
      return FALSE;
  }

  return TRUE;
}

/**
 * gst_device_has_classes:
 * @device: a #GstDevice
381
 * @classes: a "/"-separated list of device classes to match, only match if
382
 *  all classes are matched
383 384 385 386 387 388 389 390 391 392 393 394 395
 *
 * Check if @device matches all of the given classes
 *
 * Returns: %TRUE if @device matches.
 *
 * Since: 1.4
 */
gboolean
gst_device_has_classes (GstDevice * device, const gchar * classes)
{
  gchar **classesv;
  gboolean res;

Olivier Crête's avatar
Olivier Crête committed
396 397 398 399 400
  g_return_val_if_fail (GST_IS_DEVICE (device), FALSE);

  if (!classes)
    return TRUE;

401 402 403 404 405 406 407 408
  classesv = g_strsplit (classes, "/", 0);

  res = gst_device_has_classesv (device, classesv);

  g_strfreev (classesv);

  return res;
}