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
gst_device_class_init(GstDeviceClass * klass)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
gst_device_init(GstDevice * device)111 gst_device_init (GstDevice * device)
112 {
113 device->priv = gst_device_get_instance_private (device);
114 }
115
116 static void
gst_device_finalize(GObject * object)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
gst_device_get_property(GObject * object,guint prop_id,GValue * value,GParamSpec * pspec)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
gst_device_set_property(GObject * object,guint prop_id,const GValue * value,GParamSpec * pspec)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 *
gst_device_create_element(GstDevice * device,const gchar * name)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 /* Ensure that the reference is floating. Bindings might have a hard time
216 * making sure that the reference is indeed still floating after returning
217 * here */
218 if (element)
219 g_object_force_floating ((GObject *) element);
220
221 return element;
222 }
223
224 /**
225 * gst_device_get_caps:
226 * @device: a #GstDevice
227 *
228 * Getter for the #GstCaps that this device supports.
229 *
230 * Returns: (nullable): The #GstCaps supported by this device. Unref with
231 * gst_caps_unref() when done.
232 *
233 * Since: 1.4
234 */
235 GstCaps *
gst_device_get_caps(GstDevice * device)236 gst_device_get_caps (GstDevice * device)
237 {
238 g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
239
240 if (device->priv->caps)
241 return gst_caps_ref (device->priv->caps);
242 else
243 return NULL;
244 }
245
246 /**
247 * gst_device_get_display_name:
248 * @device: a #GstDevice
249 *
250 * Gets the user-friendly name of the device.
251 *
252 * Returns: The device name. Free with g_free() after use.
253 *
254 * Since: 1.4
255 */
256 gchar *
gst_device_get_display_name(GstDevice * device)257 gst_device_get_display_name (GstDevice * device)
258 {
259 g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
260
261 return
262 g_strdup (device->priv->display_name ? device->priv->display_name : "");
263 }
264
265 /**
266 * gst_device_get_device_class:
267 * @device: a #GstDevice
268 *
269 * Gets the "class" of a device. This is a "/" separated list of
270 * classes that represent this device. They are a subset of the
271 * classes of the #GstDeviceProvider that produced this device.
272 *
273 * Returns: The device class. Free with g_free() after use.
274 *
275 * Since: 1.4
276 */
277 gchar *
gst_device_get_device_class(GstDevice * device)278 gst_device_get_device_class (GstDevice * device)
279 {
280 g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
281
282 if (device->priv->device_class != NULL)
283 return g_strdup (device->priv->device_class);
284 else
285 return g_strdup ("");
286 }
287
288 /**
289 * gst_device_get_properties:
290 * @device: a #GstDevice
291 *
292 * Gets the extra properties of a device.
293 *
294 * Returns: (nullable): The extra properties or %NULL when there are none.
295 * Free with gst_structure_free() after use.
296 *
297 * Since: 1.6
298 */
299 GstStructure *
gst_device_get_properties(GstDevice * device)300 gst_device_get_properties (GstDevice * device)
301 {
302 g_return_val_if_fail (GST_IS_DEVICE (device), NULL);
303
304 if (device->priv->properties != NULL)
305 return gst_structure_copy (device->priv->properties);
306 else
307 return NULL;
308 }
309
310 /**
311 * gst_device_reconfigure_element:
312 * @device: a #GstDevice
313 * @element: a #GstElement
314 *
315 * Tries to reconfigure an existing element to use the device. If this
316 * function fails, then one must destroy the element and create a new one
317 * using gst_device_create_element().
318 *
319 * Note: This should only be implemented for elements can change their
320 * device in the PLAYING state.
321 *
322 * Returns: %TRUE if the element could be reconfigured to use this device,
323 * %FALSE otherwise.
324 *
325 * Since: 1.4
326 */
327 gboolean
gst_device_reconfigure_element(GstDevice * device,GstElement * element)328 gst_device_reconfigure_element (GstDevice * device, GstElement * element)
329 {
330 GstDeviceClass *klass = GST_DEVICE_GET_CLASS (device);
331
332 g_return_val_if_fail (GST_IS_DEVICE (device), FALSE);
333
334 if (klass->reconfigure_element)
335 return klass->reconfigure_element (device, element);
336 else
337 return FALSE;
338 }
339
340 /**
341 * gst_device_has_classesv:
342 * @device: a #GstDevice
343 * @classes: (array zero-terminated=1): a %NULL terminated array of classes
344 * to match, only match if all classes are matched
345 *
346 * Check if @factory matches all of the given classes
347 *
348 * Returns: %TRUE if @device matches.
349 *
350 * Since: 1.4
351 */
352 gboolean
gst_device_has_classesv(GstDevice * device,gchar ** classes)353 gst_device_has_classesv (GstDevice * device, gchar ** classes)
354 {
355 g_return_val_if_fail (GST_IS_DEVICE (device), FALSE);
356
357 if (!classes)
358 return TRUE;
359
360 for (; classes[0]; classes++) {
361 const gchar *klass = classes[0];
362 const gchar *found;
363 guint len;
364
365 if (*klass == '\0')
366 continue;
367
368 found = strstr (device->priv->device_class, klass);
369
370 if (!found)
371 return FALSE;
372 if (found != device->priv->device_class && *(found - 1) != '/')
373 return FALSE;
374
375 len = strlen (klass);
376 if (found[len] != 0 && found[len] != '/')
377 return FALSE;
378 }
379
380 return TRUE;
381 }
382
383 /**
384 * gst_device_has_classes:
385 * @device: a #GstDevice
386 * @classes: a "/"-separated list of device classes to match, only match if
387 * all classes are matched
388 *
389 * Check if @device matches all of the given classes
390 *
391 * Returns: %TRUE if @device matches.
392 *
393 * Since: 1.4
394 */
395 gboolean
gst_device_has_classes(GstDevice * device,const gchar * classes)396 gst_device_has_classes (GstDevice * device, const gchar * classes)
397 {
398 gchar **classesv;
399 gboolean res;
400
401 g_return_val_if_fail (GST_IS_DEVICE (device), FALSE);
402
403 if (!classes)
404 return TRUE;
405
406 classesv = g_strsplit (classes, "/", 0);
407
408 res = gst_device_has_classesv (device, classesv);
409
410 g_strfreev (classesv);
411
412 return res;
413 }
414