GstDeviceMonitor: GStreamer 1.0 Core Reference Manual

## GstDeviceMonitor GstDeviceMonitor — A device monitor and prober |

## Functions

GstDeviceMonitor * | gst_device_monitor_new ()
GstBus * | gst_device_monitor_get_bus ()
guint | gst_device_monitor_add_filter ()
gboolean | gst_device_monitor_remove_filter ()
gboolean | gst_device_monitor_start ()
void | gst_device_monitor_stop ()
GList * | gst_device_monitor_get_devices ()
gchar ** | gst_device_monitor_get_providers ()
gboolean | gst_device_monitor_get_show_all_devices ()
void | gst_device_monitor_set_show_all_devices ()
gchar ** | gst_device_provider_get_hidden_providers ()
void | gst_device_provider_hide_provider ()
void | gst_device_provider_unhide_provider ()

## Types and Values

struct | GstDeviceMonitor
struct | GstDeviceMonitorClass

## Includes

    #include <gst/gst.h>

## Description

Applications should create a GstDeviceMonitor when they want to probe, list and monitor devices of a specific type. The GstDeviceMonitor will create the appropriate GstDeviceProvider objects and manage them. It will then post messages on its GstBus for devices that have been added and removed.

The device monitor will monitor all devices matching the filters that the application has set.

The basic use pattern of a device monitor is as follows:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    static gboolean
    my_bus_func (GstBus * bus, GstMessage * message, gpointer user_data)
    {
       GstDevice *device;
       gchar *name;

       switch (GST_MESSAGE_TYPE (message)) {
         case GST_MESSAGE_DEVICE_ADDED:
           gst_message_parse_device_added (message, &device);
           name = gst_device_get_display_name (device);
           g_print("Device added: %s\n", name);
           g_free (name);
           break;
         case GST_MESSAGE_DEVICE_REMOVED:
           gst_message_parse_device_removed (message, &device);
           name = gst_device_get_display_name (device);
           g_print("Device removed: %s\n", name);
           g_free (name);
           break;
         default:
           break;
       }

       return G_SOURCE_CONTINUE;
    }

    GstDeviceMonitor *
    setup_raw_video_source_device_monitor (void) {
       GstDeviceMonitor *monitor;
       GstBus *bus;
       GstCaps *caps;

       monitor = gst_device_monitor_new ();

       bus = gst_device_monitor_get_bus (monitor);
       gst_bus_add_watch (bus, my_bus_func, NULL);
       gst_object_unref (bus);

       caps = gst_caps_new_empty_simple ("video/x-raw");
       gst_device_monitor_add_filter (monitor, "Video/Source", caps);
       gst_caps_unref (caps);

       gst_device_monitor_start (monitor);

       return monitor;
    }

## Functions

### gst_device_monitor_new ()

    GstDeviceMonitor *
    gst_device_monitor_new (void);

Create a new GstDeviceMonitor

#### Returns

a new device monitor.

[transfer full]

Since: 1.4

### gst_device_monitor_get_bus ()

    GstBus *
    gst_device_monitor_get_bus (GstDeviceMonitor *monitor);

Gets the GstBus of this GstDeviceMonitor

#### Parameters

monitor | a GstDeviceProvider |

#### Returns

a GstBus.

[transfer full]

Since: 1.4

### gst_device_monitor_add_filter ()

    guint
    gst_device_monitor_add_filter (GstDeviceMonitor *monitor,
                                   const gchar *classes,
                                   GstCaps *caps);

Adds a filter for which GstDevice will be monitored, any device that matches all these classes and the GstCaps will be returned.

If this function is called multiple times to add more filters, each will be matched independently. That is, adding more filters will not further restrict what devices are matched.

The GstCaps supported by the device as returned by `gst_device_get_caps()` are not intersected with caps filters added using this function.

Filters must be added before the GstDeviceMonitor is started.

#### Parameters

monitor | a device monitor |
classes | device classes to use as filter or `NULL` for any class. | [allow-none]
caps | the GstCaps to filter or `NULL` for ANY. | [allow-none]

#### Returns

The id of the new filter or 0 if no provider matched the filter's classes.

Since: 1.4

### gst_device_monitor_remove_filter ()

    gboolean
    gst_device_monitor_remove_filter (GstDeviceMonitor *monitor,
                                      guint filter_id);

Removes a filter from the GstDeviceMonitor using the id that was returned by `gst_device_monitor_add_filter()`.

#### Parameters

monitor | a device monitor |
filter_id | the id of the filter |

#### Returns

`TRUE` of the filter id was valid, `FALSE` otherwise

Since: 1.4

### gst_device_monitor_start ()

    gboolean
    gst_device_monitor_start (GstDeviceMonitor *monitor);

Starts monitoring the devices, one this has succeeded, the `GST_MESSAGE_DEVICE_ADDED` and `GST_MESSAGE_DEVICE_REMOVED` messages will be emitted on the bus when the list of devices changes.

#### Parameters

monitor | A GstDeviceMonitor |

#### Returns

`TRUE` if the device monitoring could be started

Since: 1.4

### gst_device_monitor_stop ()

    void
    gst_device_monitor_stop (GstDeviceMonitor *monitor);

Stops monitoring the devices.

#### Parameters

monitor | A GstDeviceProvider |

Since: 1.4

### gst_device_monitor_get_devices ()

    GList *
    gst_device_monitor_get_devices (GstDeviceMonitor *monitor);

Gets a list of devices from all of the relevant monitors. This may actually probe the hardware if the monitor is not currently started.

#### Parameters

monitor | A GstDeviceProvider |

#### Returns

a GList of GstDevice.

[transfer full][element-type GstDevice]

Since: 1.4

### gst_device_monitor_get_providers ()

    gchar **
    gst_device_monitor_get_providers (GstDeviceMonitor *monitor);

Get a list of the currently selected device provider factories.

This

#### Parameters

monitor | a GstDeviceMonitor |

#### Returns

A list of device provider factory names that are currently being monitored by `monitor` or `NULL` when nothing is being monitored.

[transfer full][array zero-terminated=1][element-type gchar*]

Since: 1.6

### gst_device_monitor_get_show_all_devices ()

    gboolean
    gst_device_monitor_get_show_all_devices
                                   (GstDeviceMonitor *monitor);

Get if `monitor` is curretly showing all devices, even those from hidden providers.

#### Parameters

monitor | a GstDeviceMonitor |

#### Returns

`TRUE` when all devices will be shown.

Since: 1.6

### gst_device_monitor_set_show_all_devices ()

    void
    gst_device_monitor_set_show_all_devices
                                   (GstDeviceMonitor *monitor,
                                    gboolean show_all);

Set if all devices should be visible, even those devices from hidden providers. Setting `show_all` to true might show some devices multiple times.

#### Parameters

monitor | a GstDeviceMonitor |
show_all | show all devices |

Since: 1.6

### gst_device_provider_get_hidden_providers ()

    gchar **
    gst_device_provider_get_hidden_providers
                                   (GstDeviceProvider *provider);

Get the provider factory names of the GstDeviceProvider instances that are hidden by `provider` .

#### Parameters

provider | a GstDeviceProvider |

#### Returns

a list of hidden providers factory names or `NULL` when nothing is hidden by `provider` . Free with g_strfreev.

[transfer full][array zero-terminated=1][element-type gchar*]

Since: 1.6

### gst_device_provider_hide_provider ()

    void
    gst_device_provider_hide_provider (GstDeviceProvider *provider,
                                       const gchar *name);

Make `provider` hide the devices from the factory with `name` .

This function is used when `provider` will also provide the devices reported by provider factory `name` . A monitor should stop monitoring the device provider with `name` to avoid duplicate devices.

#### Parameters

provider | a GstDeviceProvider |
name | a provider factory name |

Since: 1.6

### gst_device_provider_unhide_provider ()

    void
    gst_device_provider_unhide_provider (GstDeviceProvider *provider,
                                         const gchar *name);

Make `provider` unhide the devices from factory `name` .

This function is used when `provider` will no longer provide the devices reported by provider factory `name` . A monitor should start monitoring the devices from provider factory `name` in order to see all devices again.

#### Parameters

provider | a GstDeviceProvider |
name | a provider factory name |

Since: 1.6

## Types and Values

### struct GstDeviceMonitor

    struct GstDeviceMonitor {
      GstObject                parent;
    };

Opaque device monitor object structure.

#### Members

GstObject `parent`; | the parent GstObject structure |

Since: 1.4

### struct GstDeviceMonitorClass

    struct GstDeviceMonitorClass {
      GstObjectClass           parent_class;
    };

Opaque device monitor class structure.

#### Members

Since: 1.4

## See Also

GstDevice, GstDeviceProvider