Commit bd26fa7c authored by Tim-Philipp Müller's avatar Tim-Philipp Müller 🐠

devicemonitor: some docs additions and fixes

parent 97fe853e
...@@ -42,6 +42,11 @@ typedef struct _GstDeviceMonitorPrivate GstDeviceMonitorPrivate; ...@@ -42,6 +42,11 @@ typedef struct _GstDeviceMonitorPrivate GstDeviceMonitorPrivate;
#define GST_DEVICE_MONITOR_CAST(obj) ((GstDeviceMonitor *)(obj)) #define GST_DEVICE_MONITOR_CAST(obj) ((GstDeviceMonitor *)(obj))
/**
* GstDeviceMonitor:
*
* Since: 1.4
*/
struct _GstDeviceMonitor { struct _GstDeviceMonitor {
GstObject parent; GstObject parent;
...@@ -59,7 +64,7 @@ struct _GstDeviceMonitor { ...@@ -59,7 +64,7 @@ struct _GstDeviceMonitor {
* GstDeviceMonitorClass: * GstDeviceMonitorClass:
* @factory: a pointer to the #GstDeviceMonitorFactory that creates this * @factory: a pointer to the #GstDeviceMonitorFactory that creates this
* monitor * monitor
* @get_devices: Returns a list of devices that are currently available. * @probe: Returns a list of devices that are currently available.
* This should never block. * This should never block.
* @start: Starts monitoring for new devices. * @start: Starts monitoring for new devices.
* @stop: Stops monitoring for new devices * @stop: Stops monitoring for new devices
...@@ -79,7 +84,7 @@ struct _GstDeviceMonitorClass { ...@@ -79,7 +84,7 @@ struct _GstDeviceMonitorClass {
gboolean (*start) (GstDeviceMonitor * monitor); gboolean (*start) (GstDeviceMonitor * monitor);
void (*stop) (GstDeviceMonitor * monitor); void (*stop) (GstDeviceMonitor * monitor);
/*< private >*/
gpointer metadata; gpointer metadata;
/*< private >*/ /*< private >*/
......
...@@ -18,7 +18,7 @@ ...@@ -18,7 +18,7 @@
* Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA. * Boston, MA 02111-1307, USA.
*/ */
/* FIXME: documentation section! */
#ifdef HAVE_CONFIG_H #ifdef HAVE_CONFIG_H
#include "config.h" #include "config.h"
#endif #endif
...@@ -169,56 +169,58 @@ gst_global_device_monitor_dispose (GObject * object) ...@@ -169,56 +169,58 @@ gst_global_device_monitor_dispose (GObject * object)
* *
* Returns: (transfer full) (element-type GstDevice): a #GList of * Returns: (transfer full) (element-type GstDevice): a #GList of
* #GstDevice * #GstDevice
*
* Since: 1.4
*/ */
GList * GList *
gst_global_device_monitor_get_devices (GstGlobalDeviceMonitor * self) gst_global_device_monitor_get_devices (GstGlobalDeviceMonitor * monitor)
{ {
GList *devices = NULL; GList *devices = NULL;
guint i; guint i;
guint cookie; guint cookie;
g_return_val_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (self), NULL); g_return_val_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (monitor), NULL);
GST_OBJECT_LOCK (self); GST_OBJECT_LOCK (monitor);
again: again:
g_list_free_full (devices, gst_object_unref); g_list_free_full (devices, gst_object_unref);
devices = NULL; devices = NULL;
cookie = self->priv->cookie; cookie = monitor->priv->cookie;
for (i = 0; i < self->priv->monitors->len; i++) { for (i = 0; i < monitor->priv->monitors->len; i++) {
GList *tmpdev; GList *tmpdev;
GstDeviceMonitor *monitor = GstDeviceMonitor *device_monitor =
gst_object_ref (g_ptr_array_index (self->priv->monitors, i)); gst_object_ref (g_ptr_array_index (monitor->priv->monitors, i));
GList *item; GList *item;
GST_OBJECT_UNLOCK (self); GST_OBJECT_UNLOCK (monitor);
tmpdev = gst_device_monitor_get_devices (monitor); tmpdev = gst_device_monitor_get_devices (device_monitor);
for (item = tmpdev; item; item = item->next) { for (item = tmpdev; item; item = item->next) {
GstDevice *dev = GST_DEVICE (item->data); GstDevice *dev = GST_DEVICE (item->data);
GstCaps *caps = gst_device_get_caps (dev); GstCaps *caps = gst_device_get_caps (dev);
if (gst_caps_can_intersect (self->priv->caps, caps) && if (gst_caps_can_intersect (monitor->priv->caps, caps) &&
gst_device_has_classes (dev, self->priv->classes)) gst_device_has_classes (dev, monitor->priv->classes))
devices = g_list_prepend (devices, gst_object_ref (dev)); devices = g_list_prepend (devices, gst_object_ref (dev));
gst_caps_unref (caps); gst_caps_unref (caps);
} }
g_list_free_full (tmpdev, gst_object_unref); g_list_free_full (tmpdev, gst_object_unref);
gst_object_unref (monitor); gst_object_unref (device_monitor);
GST_OBJECT_LOCK (self); GST_OBJECT_LOCK (monitor);
if (self->priv->cookie != cookie) if (monitor->priv->cookie != cookie)
goto again; goto again;
} }
GST_OBJECT_UNLOCK (self); GST_OBJECT_UNLOCK (monitor);
return devices; return devices;
} }
...@@ -232,39 +234,42 @@ again: ...@@ -232,39 +234,42 @@ again:
* signals will be emitted when the list of devices changes. * signals will be emitted when the list of devices changes.
* *
* Returns: %TRUE if the device monitoring could be started * Returns: %TRUE if the device monitoring could be started
*
* Since: 1.4
*/ */
gboolean gboolean
gst_global_device_monitor_start (GstGlobalDeviceMonitor * self) gst_global_device_monitor_start (GstGlobalDeviceMonitor * monitor)
{ {
guint i; guint i;
g_return_val_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (self), FALSE); g_return_val_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (monitor), FALSE);
GST_OBJECT_LOCK (self); GST_OBJECT_LOCK (monitor);
if (self->priv->monitors->len == 0) { if (monitor->priv->monitors->len == 0) {
GST_OBJECT_UNLOCK (self); GST_OBJECT_UNLOCK (monitor);
return FALSE; return FALSE;
} }
gst_bus_set_flushing (self->priv->bus, FALSE); gst_bus_set_flushing (monitor->priv->bus, FALSE);
for (i = 0; i < self->priv->monitors->len; i++) { for (i = 0; i < monitor->priv->monitors->len; i++) {
if (!gst_device_monitor_start (g_ptr_array_index (self->priv->monitors, i))) { if (!gst_device_monitor_start (g_ptr_array_index (monitor->priv->monitors,
gst_bus_set_flushing (self->priv->bus, TRUE); i))) {
gst_bus_set_flushing (monitor->priv->bus, TRUE);
for (; i != 0; i--) for (; i != 0; i--)
gst_device_monitor_stop (g_ptr_array_index (self->priv->monitors, gst_device_monitor_stop (g_ptr_array_index (monitor->priv->monitors,
i - 1)); i - 1));
GST_OBJECT_UNLOCK (self); GST_OBJECT_UNLOCK (monitor);
return FALSE; return FALSE;
} }
} }
self->priv->started = TRUE; monitor->priv->started = TRUE;
GST_OBJECT_UNLOCK (self); GST_OBJECT_UNLOCK (monitor);
return TRUE; return TRUE;
} }
...@@ -274,53 +279,66 @@ gst_global_device_monitor_start (GstGlobalDeviceMonitor * self) ...@@ -274,53 +279,66 @@ gst_global_device_monitor_start (GstGlobalDeviceMonitor * self)
* @monitor: A #GstDeviceMonitor * @monitor: A #GstDeviceMonitor
* *
* Stops monitoring the devices. * Stops monitoring the devices.
*
* Since: 1.4
*/ */
void void
gst_global_device_monitor_stop (GstGlobalDeviceMonitor * self) gst_global_device_monitor_stop (GstGlobalDeviceMonitor * monitor)
{ {
guint i; guint i;
g_return_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (self)); g_return_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (monitor));
gst_bus_set_flushing (self->priv->bus, TRUE); gst_bus_set_flushing (monitor->priv->bus, TRUE);
GST_OBJECT_LOCK (self); GST_OBJECT_LOCK (monitor);
for (i = 0; i < self->priv->monitors->len; i++) for (i = 0; i < monitor->priv->monitors->len; i++)
gst_device_monitor_stop (g_ptr_array_index (self->priv->monitors, i)); gst_device_monitor_stop (g_ptr_array_index (monitor->priv->monitors, i));
self->priv->started = FALSE; monitor->priv->started = FALSE;
GST_OBJECT_UNLOCK (self); GST_OBJECT_UNLOCK (monitor);
} }
/**
* gst_global_device_monitor_set_classes_filter:
* @self: the global device monitor
* @classes: device classes to use as filter
*
* Filter devices monitored by device class, e.g. in case you are only
* interested in a certain type of device like audio devices or
* video sources.
*
* Since: 1.4
*/
void void
gst_global_device_monitor_set_classes_filter (GstGlobalDeviceMonitor * self, gst_global_device_monitor_set_classes_filter (GstGlobalDeviceMonitor * monitor,
const gchar * classes) const gchar * classes)
{ {
GList *factories = NULL; GList *factories = NULL;
guint i; guint i;
g_return_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (self)); g_return_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (monitor));
g_return_if_fail (!self->priv->started); g_return_if_fail (!monitor->priv->started);
GST_OBJECT_LOCK (self); GST_OBJECT_LOCK (monitor);
if (!strcmp (self->priv->classes, classes)) { if (!strcmp (monitor->priv->classes, classes)) {
GST_OBJECT_UNLOCK (self); GST_OBJECT_UNLOCK (monitor);
return; return;
} }
g_free (self->priv->classes); g_free (monitor->priv->classes);
self->priv->classes = g_strdup (classes); monitor->priv->classes = g_strdup (classes);
factories = factories = gst_device_monitor_factory_list_get_device_monitors (classes, 1);
gst_device_monitor_factory_list_get_device_monitors (self->priv->classes,
1);
for (i = 0; i < self->priv->monitors->len; i++) { for (i = 0; i < monitor->priv->monitors->len; i++) {
GstDeviceMonitor *monitor = g_ptr_array_index (self->priv->monitors, i); GstDeviceMonitor *dev_monitor;
GstDeviceMonitorFactory *f = gst_device_monitor_get_factory (monitor); GstDeviceMonitorFactory *f;
GList *item; GList *item;
dev_monitor = g_ptr_array_index (monitor->priv->monitors, i);
f = gst_device_monitor_get_factory (dev_monitor);
item = g_list_find (factories, f); item = g_list_find (factories, f);
if (item) { if (item) {
...@@ -333,76 +351,111 @@ gst_global_device_monitor_set_classes_filter (GstGlobalDeviceMonitor * self, ...@@ -333,76 +351,111 @@ gst_global_device_monitor_set_classes_filter (GstGlobalDeviceMonitor * self,
/* If it's not in our list, them remove it from the list of monitors. /* If it's not in our list, them remove it from the list of monitors.
*/ */
self->priv->cookie++; monitor->priv->cookie++;
gst_global_device_monitor_remove (self, i); gst_global_device_monitor_remove (monitor, i);
i--; i--;
} }
} }
while (factories) { while (factories) {
GstDeviceMonitorFactory *factory = factories->data; GstDeviceMonitorFactory *factory = factories->data;
GstDeviceMonitor *monitor; GstDeviceMonitor *device_monitor;
factories = g_list_remove (factories, factory); factories = g_list_remove (factories, factory);
monitor = gst_device_monitor_factory_get (factory); device_monitor = gst_device_monitor_factory_get (factory);
if (monitor) { if (device_monitor) {
GstBus *bus = gst_device_monitor_get_bus (monitor); GstBus *bus = gst_device_monitor_get_bus (device_monitor);
gst_bus_enable_sync_message_emission (bus); gst_bus_enable_sync_message_emission (bus);
g_signal_connect (bus, "sync-message", g_signal_connect (bus, "sync-message",
G_CALLBACK (bus_sync_message), self); G_CALLBACK (bus_sync_message), monitor);
gst_object_unref (bus); gst_object_unref (bus);
g_ptr_array_add (self->priv->monitors, monitor); g_ptr_array_add (monitor->priv->monitors, device_monitor);
self->priv->cookie++; monitor->priv->cookie++;
} }
gst_object_unref (factory); gst_object_unref (factory);
} }
GST_OBJECT_UNLOCK (self); GST_OBJECT_UNLOCK (monitor);
} }
/**
* gst_global_device_monitor_get_classes_filter:
* @monitor: the global device monitor
*
* Return the type (device classes) filter active for device filtering.
*
* Returns: string of device classes that are being filtered.
*
* Since: 1.4
*/
gchar * gchar *
gst_global_device_monitor_get_classes_filter (GstGlobalDeviceMonitor * self) gst_global_device_monitor_get_classes_filter (GstGlobalDeviceMonitor * monitor)
{ {
gchar *res; gchar *res;
g_return_val_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (self), 0); g_return_val_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (monitor), 0);
GST_OBJECT_LOCK (self); GST_OBJECT_LOCK (monitor);
res = g_strdup (self->priv->classes); res = g_strdup (monitor->priv->classes);
GST_OBJECT_UNLOCK (self); GST_OBJECT_UNLOCK (monitor);
return res; return res;
} }
/**
* gst_global_device_monitor_set_caps_filter:
* @monitor: the global device monitor
* @caps: caps to filter
*
* Set caps to use as filter for devices. By default ANY caps are used,
* meaning no caps filter is active.
*
* Since: 1.4
*/
void void
gst_global_device_monitor_set_caps_filter (GstGlobalDeviceMonitor * self, gst_global_device_monitor_set_caps_filter (GstGlobalDeviceMonitor * monitor,
GstCaps * caps) GstCaps * caps)
{ {
g_return_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (self)); g_return_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (monitor));
g_return_if_fail (GST_IS_CAPS (caps)); g_return_if_fail (GST_IS_CAPS (caps));
GST_OBJECT_LOCK (self); GST_OBJECT_LOCK (monitor);
gst_caps_replace (&self->priv->caps, caps); gst_caps_replace (&monitor->priv->caps, caps);
GST_OBJECT_UNLOCK (self); GST_OBJECT_UNLOCK (monitor);
} }
/**
* gst_global_device_monitor_get_caps_filter:
* @monitor: a global device monitor
*
* Returns: (transfer full): the filter caps that are active (or ANY caps)
*
* Since: 1.4
*/
GstCaps * GstCaps *
gst_global_device_monitor_get_caps_filter (GstGlobalDeviceMonitor * self) gst_global_device_monitor_get_caps_filter (GstGlobalDeviceMonitor * monitor)
{ {
GstCaps *res; GstCaps *res;
g_return_val_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (self), NULL); g_return_val_if_fail (GST_IS_GLOBAL_DEVICE_MONITOR (monitor), NULL);
GST_OBJECT_LOCK (self); GST_OBJECT_LOCK (monitor);
res = gst_caps_ref (self->priv->caps); res = gst_caps_ref (monitor->priv->caps);
GST_OBJECT_UNLOCK (self); GST_OBJECT_UNLOCK (monitor);
return res; return res;
} }
/**
* gst_global_device_monitor_new:
*
* Returns: (transfer full): a new global device monitor.
*
* Since: 1.4
*/
GstGlobalDeviceMonitor * GstGlobalDeviceMonitor *
gst_global_device_monitor_new (void) gst_global_device_monitor_new (void)
{ {
...@@ -416,6 +469,8 @@ gst_global_device_monitor_new (void) ...@@ -416,6 +469,8 @@ gst_global_device_monitor_new (void)
* Gets the #GstBus of this #GstGlobalDeviceMonitor * Gets the #GstBus of this #GstGlobalDeviceMonitor
* *
* Returns: (transfer full): a #GstBus * Returns: (transfer full): a #GstBus
*
* Since: 1.4
*/ */
GstBus * GstBus *
gst_global_device_monitor_get_bus (GstGlobalDeviceMonitor * monitor) gst_global_device_monitor_get_bus (GstGlobalDeviceMonitor * monitor)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment