GVolumeMonitor

## GVolumeMonitor GVolumeMonitor — Volume Monitor |

## Synopsis

    #include <gio/gio.h>

                        GVolumeMonitor;
    #define             G_VOLUME_MONITOR_EXTENSION_POINT_NAME
    GVolumeMonitor*     g_volume_monitor_get                (void);
    GList*              g_volume_monitor_get_connected_drives
                                                            (GVolumeMonitor *volume_monitor);
    GList*              g_volume_monitor_get_volumes        (GVolumeMonitor *volume_monitor);
    GList*              g_volume_monitor_get_mounts         (GVolumeMonitor *volume_monitor);
    GVolume*            g_volume_monitor_adopt_orphan_mount (GMount *mount);
    GMount*             g_volume_monitor_get_mount_for_uuid (GVolumeMonitor *volume_monitor,
                                                             const char *uuid);
    GVolume*            g_volume_monitor_get_volume_for_uuid
                                                            (GVolumeMonitor *volume_monitor,
                                                             const char *uuid);

## Object Hierarchy

      GObject
       +----GVolumeMonitor

## Signals

      "drive-changed"                                  : Run Last
      "drive-connected"                                : Run Last
      "drive-disconnected"                             : Run Last
      "mount-added"                                    : Run Last
      "mount-changed"                                  : Run Last
      "mount-pre-unmount"                              : Run Last
      "mount-removed"                                  : Run Last
      "volume-added"                                   : Run Last
      "volume-changed"                                 : Run Last
      "volume-removed"                                 : Run Last

## Description

GVolumeMonitor is for listing the user interesting devices and volumes on the computer. In other words, what a file selector or file manager would show in a sidebar.

## Details

### GVolumeMonitor

    typedef struct _GVolumeMonitor GVolumeMonitor;

A Volume Monitor that watches for volume events.

### G_VOLUME_MONITOR_EXTENSION_POINT_NAME

    #define G_VOLUME_MONITOR_EXTENSION_POINT_NAME "gio-volume-monitor"

Extension point for volume monitor functionality. See Extending GIO.

### g_volume_monitor_get ()

    GVolumeMonitor*     g_volume_monitor_get                (void);

Gets the volume monitor used by gio.

Returns : | a reference to the GVolumeMonitor used by gio. Call `g_object_unref()` when done with it.

### g_volume_monitor_get_connected_drives ()

    GList*              g_volume_monitor_get_connected_drives
                                                            (GVolumeMonitor *volume_monitor);

Gets a list of drives connected to the system.

The returned list should be freed with `g_list_free()`, after its elements have been unreffed with `g_object_unref()`.

`volume_monitor` : | a GVolumeMonitor.
Returns : | a GList of connected GDrives

### g_volume_monitor_get_volumes ()

    GList*              g_volume_monitor_get_volumes        (GVolumeMonitor *volume_monitor);

Gets a list of the volumes on the system.

The returned list should be freed with `g_list_free()`, after its elements have been unreffed with `g_object_unref()`.

`volume_monitor` : | a GVolumeMonitor.
Returns : | a GList of GVolumes.

### g_volume_monitor_get_mounts ()

    GList*              g_volume_monitor_get_mounts         (GVolumeMonitor *volume_monitor);

Gets a list of the mounts on the system.

The returned list should be freed with `g_list_free()`, after its elements have been unreffed with `g_object_unref()`.

`volume_monitor` : | a GVolumeMonitor.
Returns : | a GList of GMounts

### g_volume_monitor_adopt_orphan_mount ()

    GVolume*            g_volume_monitor_adopt_orphan_mount (GMount *mount);

This function should be called by any GVolumeMonitor implementation when a new GMount object is created that is not associated with a GVolume object. It must be called just before emitting the `mount_added` signal.

If the return value is not `NULL`, the caller must associate the returned GVolume object with the GMount. This involves returning it in it's `g_mount_get_volume()` implementation. The caller must also listen for the "removed" signal on the returned object and give up it's reference when handling that signal

Similary, if implementing `g_volume_monitor_adopt_orphan_mount()`, the implementor must take a reference to `mount` and return it in it's `g_volume_get_mount()` implemented. Also, the implementor must listen for the "unmounted" signal on `mount` and give up it's reference upon handling that signal.

There are two main use cases for this function.

One is when implementing a user space file system driver that reads blocks of a block device that is already represented by the native volume monitor (for example a CD Audio file system driver). Such a driver will generate it's own GMount object that needs to be assoicated with the GVolume object that represents the volume.

The other is for implementing a GVolumeMonitor whose sole purpose is to return GVolume objects representing entries in the users "favorite servers" list or similar.

`mount` : | a GMount object to find a parent for
Returns : | the GVolume object that is the parent for `mount` or `NULL` if no wants to adopt the GMount.

### g_volume_monitor_get_mount_for_uuid ()

    GMount*             g_volume_monitor_get_mount_for_uuid (GVolumeMonitor *volume_monitor,
                                                             const char *uuid);

Finds a GMount object by it's UUID (see `g_mount_get_uuid()`)

`volume_monitor` : | a GVolumeMonitor.
`uuid` : | the UUID to look for
Returns : | a GMount or `NULL` if no such mount is available.

### g_volume_monitor_get_volume_for_uuid ()

    GVolume*            g_volume_monitor_get_volume_for_uuid
                                                            (GVolumeMonitor *volume_monitor,
                                                             const char *uuid);

Finds a GVolume object by it's UUID (see `g_volume_get_uuid()`)

`volume_monitor` : | a GVolumeMonitor.
`uuid` : | the UUID to look for
Returns : | a GVolume or `NULL` if no such volume is available.

## Signal Details

### The `"drive-changed"` signal

    void                user_function                      (GVolumeMonitor *volume_monitor,
                                                            GDrive         *drive,
                                                            gpointer        user_data)           : Run Last

Emitted when a drive changes.

`volume_monitor` : | The volume monitor emitting the signal.
`drive` : | the drive that changed
`user_data` : | user data set when the signal handler was connected.

### The `"drive-connected"` signal

    void                user_function                      (GVolumeMonitor *volume_monitor,
                                                            GDrive         *drive,
                                                            gpointer        user_data)           : Run Last

Emitted when a drive is connected to the system.

`volume_monitor` : | The volume monitor emitting the signal.
`drive` : | a GDrive that was connected.
`user_data` : | user data set when the signal handler was connected.

### The `"drive-disconnected"` signal

    void                user_function                      (GVolumeMonitor *volume_monitor,
                                                            GDrive         *drive,
                                                            gpointer        user_data)           : Run Last

Emitted when a drive is disconnected from the system.

`volume_monitor` : | The volume monitor emitting the signal.
`drive` : | a GDrive that was disconnected.
`user_data` : | user data set when the signal handler was connected.

### The `"mount-added"` signal

    void                user_function                      (GVolumeMonitor *volume_monitor,
                                                            GMount         *mount,
                                                            gpointer        user_data)           : Run Last

Emitted when a mount is added.

`volume_monitor` : | The volume monitor emitting the signal.
`mount` : | a GMount that was added.
`user_data` : | user data set when the signal handler was connected.

### The `"mount-changed"` signal

    void                user_function                      (GVolumeMonitor *volume_monitor,
                                                            GMount         *mount,
                                                            gpointer        user_data)           : Run Last

Emitted when a mount changes.

`volume_monitor` : | The volume monitor emitting the signal.
`mount` : | a GMount that changed.
`user_data` : | user data set when the signal handler was connected.

### The `"mount-pre-unmount"` signal

    void                user_function                      (GVolumeMonitor *volume_monitor,
                                                            GMount         *mount,
                                                            gpointer        user_data)           : Run Last

Emitted when a mount is about to be removed.

`volume_monitor` : | The volume monitor emitting the signal.
`mount` : | a GMount that is being unmounted.
`user_data` : | user data set when the signal handler was connected.

### The `"mount-removed"` signal

    void                user_function                      (GVolumeMonitor *volume_monitor,
                                                            GMount         *mount,
                                                            gpointer        user_data)           : Run Last

Emitted when a mount is removed.

`volume_monitor` : | The volume monitor emitting the signal.
`mount` : | a GMount that was removed.
`user_data` : | user data set when the signal handler was connected.

### The `"volume-added"` signal

    void                user_function                      (GVolumeMonitor *volume_monitor,
                                                            GVolume        *volume,
                                                            gpointer        user_data)           : Run Last

Emitted when a mountable volume is added to the system.

`volume_monitor` : | The volume monitor emitting the signal.
`volume` : | a GVolume that was added.
`user_data` : | user data set when the signal handler was connected.

### The `"volume-changed"` signal

    void                user_function                      (GVolumeMonitor *volume_monitor,
                                                            GVolume        *volume,
                                                            gpointer        user_data)           : Run Last

Emitted when mountable volume is changed.

`volume_monitor` : | The volume monitor emitting the signal.
`volume` : | a GVolume that changed.
`user_data` : | user data set when the signal handler was connected.

### The `"volume-removed"` signal

    void                user_function                      (GVolumeMonitor *volume_monitor,
                                                            GVolume        *volume,
                                                            gpointer        user_data)           : Run Last

Emitted when a mountable volume is removed from the system.

`volume_monitor` : | The volume monitor emitting the signal.
`volume` : | a GVolume that was removed.
`user_data` : | user data set when the signal handler was connected.

## See Also

GFileMonitor