GduPresentable

GduPresentable — Interface for devices presentable to the end user

Synopsis

                    GduPresentableIface;
const gchar *       gdu_presentable_get_id              (GduPresentable *presentable);
GduDevice *         gdu_presentable_get_device          (GduPresentable *presentable);
GduPresentable *    gdu_presentable_get_enclosing_presentable
                                                        (GduPresentable *presentable);
gchar *             gdu_presentable_get_name            (GduPresentable *presentable);
gchar *             gdu_presentable_get_description     (GduPresentable *presentable);
gchar *             gdu_presentable_get_vpd_name        (GduPresentable *presentable);
GIcon *             gdu_presentable_get_icon            (GduPresentable *presentable);
guint64             gdu_presentable_get_offset          (GduPresentable *presentable);
guint64             gdu_presentable_get_size            (GduPresentable *presentable);
GduPool *           gdu_presentable_get_pool            (GduPresentable *presentable);
gboolean            gdu_presentable_is_allocated        (GduPresentable *presentable);
gboolean            gdu_presentable_is_recognized       (GduPresentable *presentable);
GduPresentable *    gdu_presentable_get_toplevel        (GduPresentable *presentable);
guint               gdu_presentable_hash                (GduPresentable *presentable);
gboolean            gdu_presentable_equals              (GduPresentable *a,
                                                         GduPresentable *b);
gint                gdu_presentable_compare             (GduPresentable *a,
                                                         GduPresentable *b);

Description

All storage devices in UNIX and UNIX-like operating systems are mostly represented by so-called block devices at the kernel/user-land interface. UNIX block devices, including information and operations are represented by the GduDevice class.

However, from an user-interface point of view, it's useful to make a finer-grained distinction; for example it's useful to make a distinction between drives (e.g. a phyiscal hard disk, optical drives) and volumes (e.g. a mountable file system).

As such, classes encapsulating aspects of a UNIX block device (such as it being drive, volume, empty space) that are interesting to present in the user interface all implement the GduPresentable interface. This interface provides lowest-common denominator functionality assisting in the creation of user interfaces; name and icons are easily available as well as hierarchical grouping in terms of parent/child relationships. Thus, several classes such as GduVolume, GduDrive and others implement the GduPresentable interface

For example, if a device (/dev/sda) is partitioned into two partitions (/dev/sda1 and /dev/sda2), the parent/child relation look looks like this

GduDrive     (/dev/sda)
  GduVolume  (/dev/sda1)
  GduVolume  (/dev/sda2)

Some partitioning schemes (notably Master Boot Record) have a concept of nested partition tables. Supposed /dev/sda2 is an extended partition and /dev/sda5 and /dev/sda6 are logical partitions:

GduDrive       (/dev/sda)
  GduVolume    (/dev/sda1)
  GduVolume    (/dev/sda2)
    GduVolume  (/dev/sda5)
    GduVolume  (/dev/sda6)

The gdu_presentable_get_offset() function can be used to determine the ordering; this function will return the offset of a GduPresentable relative to the topmost enclosing device.

Now, consider the case where there are "holes", e.g. where there exists one or more regions on the partitioned device not occupied by any partitions. In that case, the GduPool object will create GduVolumeHole objects to patch the holes:

GduDrive           (/dev/sda)
  GduVolume        (/dev/sda1)
  GduVolume        (/dev/sda2)
    GduVolume      (/dev/sda5)
    GduVolumeHole  (no device)
    GduVolume      (/dev/sda6)
  GduVolumeHole    (no device)

Also, some devices are not partitioned. For example, the UNIX block device /dev/sr0 refers to both the optical drive and (if any medium is present) the contents of the optical disc inserted into the disc. In that case, the following structure will be created:

GduDrive     (/dev/sr0)
  GduVolume  (/dev/sr0)

If no media is available, only a single GduDrive object will exist:

GduDrive     (/dev/sr0)

Finally, unlocked LUKS Encrypted devices are represented as children of their encrypted counter parts, for example:

GduDrive       (/dev/sda)
  GduVolume    (/dev/sda1)
  GduVolume    (/dev/sda2)
    GduVolume  (/dev/dm-0)

Some devices, like RAID and LVM devices, needs to be assembled from components (e.g. "activated" or "started". This is encapsulated in the GduActivatableDrive class; this is not much different from GduDrive except that there only is a GduDevice assoicated with the object when the device itself is started. For example:

GduActivatableDrive     (no device)

will be created (e.g. synthesized) as soon as the first component of the activatable drive is available. When activated, the GduActivatableDrive will gain a GduDevice and the hierarchy looks somewhat like this

GduActivatableDrive     (/dev/md0)
  GduVolume             (/dev/md0)

To sum up, the GduPresentable interface (and classes implementing it such as GduDrive and GduVolume) describe how a drive / medium is organized such that it's easy to compose an user interface. To perform operations on devices, use gdu_presentable_get_device() and the functions on GduDevice.

Details

GduPresentableIface

typedef struct {
        GTypeInterface g_iface;

        /* signals */
        void (*changed)     (GduPresentable *presentable);
        void (*removed)     (GduPresentable *presentable);
        void (*job_changed) (GduPresentable *presentable);

        /* virtual table */
        const gchar *    (*get_id)                    (GduPresentable *presentable);
        GduDevice *      (*get_device)                (GduPresentable *presentable);
        GduPresentable * (*get_enclosing_presentable) (GduPresentable *presentable);
        gchar *          (*get_name)                  (GduPresentable *presentable);
        gchar *          (*get_description)           (GduPresentable *presentable);
        gchar *          (*get_vpd_name)              (GduPresentable *presentable);
        GIcon *          (*get_icon)                  (GduPresentable *presentable);
        guint64          (*get_offset)                (GduPresentable *presentable);
        guint64          (*get_size)                  (GduPresentable *presentable);
        GduPool *        (*get_pool)                  (GduPresentable *presentable);
        gboolean         (*is_allocated)              (GduPresentable *presentable);
        gboolean         (*is_recognized)             (GduPresentable *presentable);
} GduPresentableIface;

Interface for GduPresentable implementations.

GTypeInterface g_iface;

The parent interface.

changed ()

Signal emitted when the presentable is changed.

removed ()

Signal emitted when the presentable is removed. Recipients should release all references to the object.

job_changed ()

Signal emitted when the job state on the underlying GduDevice changes.

get_id ()

Returns a unique id for the presentable.

get_device ()

Returns the underlying GduDevice.

get_enclosing_presentable ()

Returns the GduPresentable that is the parent or NULL if there is no parent.

get_name ()

Returns a name for the presentable suitable for presentation in an user interface.

get_description ()

Returns a description of the presentable suitable for presentation in an user interface.

get_vpd_name ()

Returns a name for the presentable suitable for UI that includes Vital Product Pata.

get_icon ()

Returns an icon suitable for display in an user interface.

get_offset ()

Returns where the data represented by the presentable starts on the underlying main block device.

get_size ()

Returns the size of the presentable or zero if not allocated.

get_pool ()

Returns the GduPool object that the presentable was obtained from.

is_allocated ()

Returns whether the presentable is allocated or whether it represents free space.

is_recognized ()

Returns whether the contents of the presentable are recognized (e.g. well-known file system type).

gdu_presentable_get_id ()

const gchar *       gdu_presentable_get_id              (GduPresentable *presentable);

Gets a stable identifier for presentable.

presentable :

A GduPresentable.

Returns :

An stable identifier for presentable. Do not free, the string is owned by presentable.

gdu_presentable_get_device ()

GduDevice *         gdu_presentable_get_device          (GduPresentable *presentable);

Gets the underlying device for presentable if one is available.

presentable :

A GduPresentable.

Returns :

A GduDevice or NULL if there are no underlying device of presentable. Caller must unref the object when done with it.

gdu_presentable_get_enclosing_presentable ()

GduPresentable *    gdu_presentable_get_enclosing_presentable
                                                        (GduPresentable *presentable);

Gets the GduPresentable that is the parent of presentable or NULL if there is no parent.

presentable :

A GduPresentable.

Returns :

The GduPresentable that is a parent of presentable or NULL if presentable is the top-most presentable already. Caller must unref the object.

gdu_presentable_get_name ()

gchar *             gdu_presentable_get_name            (GduPresentable *presentable);

Gets a name for presentable suitable for presentation in an user interface.

For drives (e.g. GduDrive) this could be "80G Solid-State Disk", "500G Hard Disk", "CompactFlash Drive", "CD/DVD Drive"

For volumes (e.g. GduVolume) this string could be "Fedora (Rawhide)" (for filesystems with labels), "48G Free" (for unallocated space), "2GB Swap Space" (for swap), "430GB RAID Component" (for RAID components) and so on.

Constrast with gdu_presentable_get_vpd_name() that returns a name based on Vital Product Data including things such as the name of the vendor, the model name and so on.

presentable :

A GduPresentable.

Returns :

The name. Caller must free the string with g_free().

gdu_presentable_get_description ()

gchar *             gdu_presentable_get_description     (GduPresentable *presentable);

Gets a description for presentable suitable for presentation in an user interface.

presentable :

A GduPresentable.

Returns :

The description. Caller must free the string with g_free().

gdu_presentable_get_vpd_name ()

gchar *             gdu_presentable_get_vpd_name        (GduPresentable *presentable);

Gets a name for presentable suitable for presentation in an user interface that includes Vital Product Data details such as the name of the vendor, the model name and so on.

For drives (e.g. GduDrive) this typically includes the vendor/model strings obtained from the hardware, for example "MATSHITA DVD/CDRW UJDA775" or "ATA INTEL SSDSA2MH080G1GC".

For volumes (e.g. GduVolume) this includes information about e.g. partition infomation for example "Whole-disk volume on ATA INTEL SSDSA2MH080G1GC", "Partition 2 of ATA INTEL SSDSA2MH080G1GC".

Contrast with gdu_presentable_get_name() that may not include this information.

presentable :

A GduPresentable.

Returns :

The name. Caller must free the string with g_free().

gdu_presentable_get_icon ()

GIcon *             gdu_presentable_get_icon            (GduPresentable *presentable);

Gets a GIcon suitable for display in an user interface.

presentable :

A GduPresentable.

Returns :

The icon. Caller must free this with g_object_unref().

gdu_presentable_get_offset ()

guint64             gdu_presentable_get_offset          (GduPresentable *presentable);

Gets where the data represented by the presentable starts on the underlying main block device

presentable :

A GduPresentable.

Returns :

Offset of presentable or 0 if presentable has no underlying device.

gdu_presentable_get_size ()

guint64             gdu_presentable_get_size            (GduPresentable *presentable);

Gets the size of presentable.

presentable :

A GduPresentable.

Returns :

The size of presentable or 0 if presentable has no underlying device.

gdu_presentable_get_pool ()

GduPool *           gdu_presentable_get_pool            (GduPresentable *presentable);

Gets the GduPool that presentable stems from.

presentable :

A GduPresentable.

Returns :

A GduPool. Caller must unref object when done with it.

gdu_presentable_is_allocated ()

gboolean            gdu_presentable_is_allocated        (GduPresentable *presentable);

Determines if presentable represents an underlying block device with data.

presentable :

A GduPresentable.

Returns :

Whether presentable is allocated.

gdu_presentable_is_recognized ()

gboolean            gdu_presentable_is_recognized       (GduPresentable *presentable);

Gets whether the contents of presentable are recognized; e.g. if it's a file system, encrypted data or swap space.

presentable :

A GduPresentable.

Returns :

Whether presentable is recognized.

gdu_presentable_get_toplevel ()

GduPresentable *    gdu_presentable_get_toplevel        (GduPresentable *presentable);

Gets the top-level presentable for a given presentable.

presentable :

A GduPresentable.

Returns :

A GduPresentable or NULL if presentable is the top-most presentable. Caller must unref the object when done with it

gdu_presentable_hash ()

guint               gdu_presentable_hash                (GduPresentable *presentable);

presentable :

Returns :


gdu_presentable_equals ()

gboolean            gdu_presentable_equals              (GduPresentable *a,
                                                         GduPresentable *b);

a :

b :

Returns :


gdu_presentable_compare ()

gint                gdu_presentable_compare             (GduPresentable *a,
                                                         GduPresentable *b);

a :

b :

Returns :