GStreamer 1.0 Core Reference Manual: GstDeviceMonitor

## GstDeviceMonitor GstDeviceMonitor — A device monitor and prober |

## Functions

gboolean | gst_device_monitor_can_monitor ()
void | gst_device_monitor_class_add_metadata ()
void | gst_device_monitor_class_add_static_metadata ()
const gchar * | gst_device_monitor_class_get_metadata ()
void | gst_device_monitor_class_set_metadata ()
void | gst_device_monitor_class_set_static_metadata ()
void | gst_device_monitor_device_add ()
void | gst_device_monitor_device_remove ()
GstBus * | gst_device_monitor_get_bus ()
GList * | gst_device_monitor_get_devices ()
GstDeviceMonitorFactory * | gst_device_monitor_get_factory ()
gboolean | gst_device_monitor_register ()
gboolean | gst_device_monitor_start ()
void | gst_device_monitor_stop ()

## Types and Values

struct | GstDeviceMonitor
struct | GstDeviceMonitorClass

## Object Hierarchy

## Includes

    #include <gst/gst.h>

## Description

A GstDeviceMonitor subclass is provided by a plugin that handles devices if there is a way to programatically list connected devices. It can also optionally provide updates to the list of connected devices.

Each GstDeviceMonitor subclass is a singleton, a plugin should normally provide a single subclass for all devices.

Applications would normally use a GstGlobalDeviceMonitor to monitor devices from all revelant monitors.

## Functions

### gst_device_monitor_can_monitor ()

    gboolean
    gst_device_monitor_can_monitor (GstDeviceMonitor *monitor);

If this function returns `TRUE`, then the device monitor can monitor if devices are added or removed. Otherwise, it can only do static probing.

#### Parameters

monitor | a GstDeviceMonitor |

#### Returns

`TRUE` if the GstDeviceMonitor support monitoring, `FALSE` otherwise

### gst_device_monitor_class_add_metadata ()

    void
    gst_device_monitor_class_add_metadata (GstDeviceMonitorClass *klass,
                                           const gchar *key,
                                           const gchar *value);

Set `key` with `value` as metadata in `klass` .

#### Parameters

klass | class to set metadata for |
key | the key to set |
value | the value to set |

### gst_device_monitor_class_add_static_metadata ()

    void
    gst_device_monitor_class_add_static_metadata
                                   (GstDeviceMonitorClass *klass,
                                    const gchar *key,
                                    const gchar *value);

Set `key` with `value` as metadata in `klass` .

Same as `gst_device_monitor_class_add_metadata()`, but `value` must be a static string or an inlined string, as it will not be copied. (GStreamer plugins will be made resident once loaded, so this function can be used even from dynamically loaded plugins.)

#### Parameters

klass | class to set metadata for |
key | the key to set |
value | the value to set |

Since 1.4

### gst_device_monitor_class_get_metadata ()

    const gchar *
    gst_device_monitor_class_get_metadata (GstDeviceMonitorClass *klass,
                                           const gchar *key);

Get metadata with `key` in `klass` .

#### Parameters

klass | class to get metadata for |
key | the key to get |

#### Returns

the metadata for `key` .

Since 1.4

### gst_device_monitor_class_set_metadata ()

    void
    gst_device_monitor_class_set_metadata (GstDeviceMonitorClass *klass,
                                           const gchar *longname,
                                           const gchar *classification,
                                           const gchar *description,
                                           const gchar *author);

Sets the detailed information for a GstDeviceMonitorClass.

This function is for use in _class_init functions only.

#### Parameters

klass | class to set metadata for |
longname | The long English name of the device monitor. E.g. "File Sink" |
classification | String describing the type of device monitor, as an unordered list separated with slashes ('/'). See draft-klass.txt of the design docs for more details and common types. E.g: "Sink/File" |
description | Sentence describing the purpose of the device monitor. E.g: "Write stream to a file" |
author | Name and contact details of the author(s). Use \n to separate multiple author metadata. E.g: "Joe Bloggs <joe.blogs at foo.com>" |

Since 1.4

### gst_device_monitor_class_set_static_metadata ()

    void
    gst_device_monitor_class_set_static_metadata
                                   (GstDeviceMonitorClass *klass,
                                    const gchar *longname,
                                    const gchar *classification,
                                    const gchar *description,
                                    const gchar *author);

Sets the detailed information for a GstDeviceMonitorClass.

This function is for use in _class_init functions only.

Same as `gst_device_monitor_class_set_metadata()`, but `longname` , `classification` , `description` , and `author` must be static strings or inlined strings, as they will not be copied. (GStreamer plugins will be made resident once loaded, so this function can be used even from dynamically loaded plugins.)

#### Parameters

klass | class to set metadata for |
longname | The long English name of the element. E.g. "File Sink" |
classification | String describing the type of element, as an unordered list separated with slashes ('/'). See draft-klass.txt of the design docs for more details and common types. E.g: "Sink/File" |
description | Sentence describing the purpose of the element. E.g: "Write stream to a file" |
author | Name and contact details of the author(s). Use \n to separate multiple author metadata. E.g: "Joe Bloggs <joe.blogs at foo.com>" |

Since 1.4

### gst_device_monitor_device_add ()

    void
    gst_device_monitor_device_add (GstDeviceMonitor *monitor,
                                   GstDevice *device);

Posts a message on the monitor's GstBus to inform applications that a new device has been added.

This is for use by subclasses.

#### Parameters

monitor | a GstDeviceMonitor |
device | a GstDevice that has been added. | [transfer full]

Since 1.4

### gst_device_monitor_device_remove ()

    void
    gst_device_monitor_device_remove (GstDeviceMonitor *monitor,
                                      GstDevice *device);

Posts a message on the monitor's GstBus to inform applications that a device has been removed.

This is for use by subclasses.

#### Parameters

monitor | a GstDeviceMonitor |
device | a GstDevice that has been removed |

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 GstDeviceMonitor |

#### Returns

a GstBus.

[transfer full]

Since 1.4

### gst_device_monitor_get_devices ()

    GList *
    gst_device_monitor_get_devices (GstDeviceMonitor *monitor);

Gets a list of devices that this monitor understands. This may actually probe the hardware if the monitor is not currently started.

#### Parameters

monitor | A GstDeviceMonitor |

#### Returns

a GList of GstDevice.

[transfer full][element-type GstDevice]

Since 1.4

### gst_device_monitor_get_factory ()

    GstDeviceMonitorFactory *
    gst_device_monitor_get_factory (GstDeviceMonitor *monitor);

Retrieves the factory that was used to create this device monitor.

#### Parameters

monitor | a GstDeviceMonitor to request the device monitor factory of. |

#### Returns

the GstDeviceMonitorFactory used for creating this device monitor. no refcounting is needed.

[transfer none]

Since 1.4

### gst_device_monitor_register ()

    gboolean
    gst_device_monitor_register (GstPlugin *plugin,
                                 const gchar *name,
                                 guint rank,
                                 GType type);

Create a new device monitorfactory capable of instantiating objects of the `type` and add the factory to `plugin` .

#### Parameters

plugin | GstPlugin to register the device monitor with, or `NULL` for a static device monitor. | [allow-none]
name | name of device monitors of this type |
rank | rank of device monitor (higher rank means more importance when autoplugging) |
type | GType of device monitor to register |

#### Returns

`TRUE`, if the registering succeeded, `FALSE` on error

Since 1.4

### gst_device_monitor_start ()

    gboolean
    gst_device_monitor_start (GstDeviceMonitor *monitor);

Starts monitoring the devices. This will cause GST_MESSAGE_DEVICE messages to be posted on the monitor's bus when devices are added or removed from the system.

Since the GstDeviceMonitor is a singleton, `gst_device_monitor_start()` may already have been called by another user of the object, `gst_device_monitor_stop()` needs to be called the same number of times.

#### 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);

Decreases the use-count by one. If the use count reaches zero, this GstDeviceMonitor will stop monitoring the devices. This needs to be called the same number of times that `gst_device_monitor_start()` was called.

#### Parameters

monitor | A GstDeviceMonitor |

Since 1.4

## Types and Values

### struct GstDeviceMonitor

    struct GstDeviceMonitor {
      GstObject         parent;

      /* Protected by the Object lock */
      GList *devices;
    };

The structure of the base GstDeviceMonitor

#### Members

GstObject `parent`; | The parent GstObject |
GList *`devices`; | a GList of the GstDevice objects |

Since 1.4

### struct GstDeviceMonitorClass

    struct GstDeviceMonitorClass {
      GstObjectClass    parent_class;

      GstDeviceMonitorFactory     *factory;

      GList*      (*probe) (GstDeviceMonitor * monitor);

      gboolean    (*start) (GstDeviceMonitor * monitor);
      void        (*stop)  (GstDeviceMonitor * monitor);
    };

The structure of the base GstDeviceMonitorClass

#### Members

GstObjectClass `parent_class`; | the parent GstObjectClass structure |
GstDeviceMonitorFactory *`factory`; | a pointer to the GstDeviceMonitorFactory that creates this monitor |
`probe` () | Returns a list of devices that are currently available. This should never block. |
`start` () | Starts monitoring for new devices. Only subclasses that can know that devices have been added or remove need to implement this method. |
`stop` () | Stops monitoring for new devices. Only subclasses that implement the `start()` method need to implement this method. |

Since 1.4

## See Also

GstDevice, GstGlobalDeviceMonitor