UDisks module design

UDisksModule is a stateful object that represents a daemon module. It is supposed to hold arbitrary runtime data and perform proper initialization and cleanup within its constructor and destructor. Once initialized by UDisksModuleManager the instance is usually kept around until the daemon exits. Although proper module unloading is not currently implemented the object destructor may be actually called in some cases.

Derived UDisksModule object is supposed to implement failable initialization and return proper error that the UDisksModuleManager would propagate further up the stack. Modules are free to use failable initialization for checking runtime dependencies such as additional config files and fail if misconfigured.

UDisks module naming conventions

Every module must implement and export two symbols that are used as entry points: udisks_module_id() and udisks_module_ID_new() where ID is a string returned by udisks_module_id(). This identification string is subsequently used at several places - primarily serves as an unique and user readable module identifier (e.g. lvm2) passed in as an argument to the org.freedesktop.UDisks2.Manager.EnableModule() method call.

Physically modules are essentially regular shared objects (.so) that are loaded from $(libdir)/udisks2/modules directory (typically /usr/lib/udisks2/modules). No extra service or config files are needed, however a specific file naming of libudisks2_ID.so is required.

Module API

Other than the two entry points described in last paragraph the rest of the daemon to module interaction is done via UDisksModule class methods over an instance created by the udisks_module_ID_new() constructor. Please see particular UDisksModule methods for detailed description of each way of extending the daemon functionality. Most methods are pretty straightforward with the exception of extra drive and block object interfaces.

It's important to provide udisks_module_get_block_object_interface_types() and udisks_module_new_block_object_interface() methods (or drive respectively) always in pairs as the UDisksLinuxBlockObject and UDisksLinuxDriveObject machinery needs to register available interface skeleton types first and subsequently create target interfaces for each specified type and route uevents onto. There can be only one extra interface of a given type on a single UDisksLinuxBlockObject or UDisksLinuxDriveObject object.

In case of an existing interface for a particular type uevents are routed through the udisks_module_object_process_uevent() method of a UDisksModuleObject interface that the newly created GDBusInterfaceSkeleton interface has to implement. This call is supposed to process updated information and indicate via the return keep argument whether the particular interface is valid or should be removed from the object.

In case no GDBusInterfaceSkeleton interface of a given type is attached on the particular object, udisks_module_new_block_object_interface() or udisks_module_new_drive_object_interface() methods respectively are called in attempt to create new one. These methods are supposed to check whether the interface type is applicable for the current object and return NULL if not.

Exposing independent module objects on the master UDisks object manager as another way of daemon extensibility works in a similar way - please see udisks_module_new_object() for detailed description.

UDisksModuleIDFunc ()

gchar *
(*UDisksModuleIDFunc) (void);

Function prototype that is called by UDisksModuleManager to get unique module identifier. No initialization is supposed to be done at this point.

Since: 2.0

UDisksModuleNewFunc ()

UDisksModule *
(*UDisksModuleNewFunc) (UDisksDaemon *daemon,
                        GCancellable *cancellable,
                        GError **error);

Function prototype that creates a new UDisksModule instance. Module initialization is done at this point. This is a failable method call that properly reports module initialization failure.

Since: 2.9

udisks_module_get_name ()

const gchar *
udisks_module_get_name (UDisksModule *module);

Gets the name of the module .

Since: 2.9.0

udisks_module_new_manager ()

GDBusInterfaceSkeleton *
udisks_module_new_manager (UDisksModule *module);

Creates a new GDBusInterfaceSkeleton instance carrying an additional D-Bus interface to be exported on the UDisksManager object (at the /org/freedesktop/UDisks2/Manager path). It is a fairly simple stateless object not related to any device and serves the purpose of performing general tasks or creating new resources. Only a single manager interface can be provided by each module.

Since: 2.9.0

udisks_module_new_object ()

GDBusObjectSkeleton **
udisks_module_new_object (UDisksModule *module,
                          UDisksLinuxDevice *device);

Creates one or more GDBusObjectSkeleton objects that implement the UDisksModuleObject interface. Multiple objects may be returned by this method call, e.g. in case more than one object type is needed in order to represent a particular feature.

Objects are exported by UDisksLinuxProvider on the master object manager under the /org/freedesktop/UDisks2 path just like regular block and drive objects. This allows to create brand new object types fully handled by modules and providing custom interfaces. Objects in this scope are meant to be of virtual kind and are pretty flexible in this regard - not necessarily bound to any specific block device or drive. Perhaps even representing a group of resources. For illustration this kind of object may represent a RAID array comprised of several block devices, devices of the same kind such as loop devices or any higher level representation of something else.

Note that it's not currently possible to share module objects across multiple modules with the intention to attach extra interfaces on a foreign module object. In such case each module needs to export its own unique object, no matter if they share or represent similar kind of resource.

This method may be called quite often, for nearly any uevent received. It's done this way for broad flexibility and to give module objects a chance to claim any device needed.

Module objects are supposed to maintain internal list of claimed devices and track their validity, i.e. indicate removal only after all tracked devices are gone. Every module object may claim one or more devices. UDisksLinuxProvider essentially provides uevent routing and guarantees that existing objects are asked first to consider a claim of the device before new object is attempted to be created. This works always in the scope of a particular module, i.e. existing module objects and their claims are always considered separately for each module.

The uevent routing works as follows:

Since: 2.9.0

udisks_module_get_block_object_interface_types ()

GType *
udisks_module_get_block_object_interface_types
                               (UDisksModule *module);

Gets an array of interface skeleton GType types the module provides as additional interfaces for the UDisksLinuxBlockObject. This list is subsequently used by UDisksLinuxBlockObject to track available interfaces and to create new ones via udisks_module_new_block_object_interface().

Since: 2.9.0

udisks_module_get_drive_object_interface_types ()

GType *
udisks_module_get_drive_object_interface_types
                               (UDisksModule *module);

Gets an array of interface skeleton GType types the module provides as additional interfaces for the UDisksLinuxDriveObject. This list is subsequently used by UDisksLinuxDriveObject to track available interfaces and to create new ones via udisks_module_new_drive_object_interface().

Since: 2.9.0

udisks_module_new_block_object_interface ()

GDBusInterfaceSkeleton *
udisks_module_new_block_object_interface
                               (UDisksModule *module,
                                UDisksLinuxBlockObject *object,
                                GType interface_type);

Tries to create a new GDBusInterfaceSkeleton instance of type interface_type that is supposed to be attached on the block object . This method call is also supposed to check whether the desired interface_type is applicable for the current object and return NULL if it's not. The returned instance must implement the UDisksModuleObject interface with the udisks_module_object_process_uevent() method that is used to process uevents and controls whether the interface should be removed or not.

Since: 2.9.0

udisks_module_new_drive_object_interface ()

GDBusInterfaceSkeleton *
udisks_module_new_drive_object_interface
                               (UDisksModule *module,
                                UDisksLinuxDriveObject *object,
                                GType interface_type);

Tries to create a new GDBusInterfaceSkeleton instance of type interface_type that is supposed to be attached on the drive object . This method call is also supposed to check whether the desired interface_type is applicable for the current object and return NULL if it's not. The returned instance must implement the UDisksModuleObject interface with the udisks_module_object_process_uevent() method that is used to process uevents and controls whether the interface should be removed or not.

Since: 2.9.0

udisks_module_track_parent ()

gchar *
udisks_module_track_parent (UDisksModule *module,
                            const gchar *path,
                            gchar **uuid);

Finds a parent block device and returns its object path and UUID. If the return value is NULL, the value of uuid has not been changed. Related to udisks_daemon_get_parent_for_tracking().

Since: 2.9.0

udisks_module_get_daemon ()

UDisksDaemon *
udisks_module_get_daemon (UDisksModule *module);

Gets the daemon used by module .

Since: 2.9.0

udisks_module_object_process_uevent ()

gboolean
udisks_module_object_process_uevent (UDisksModuleObject *object,
                                     const gchar *action,
                                     UDisksLinuxDevice *device,
                                     gboolean *keep);

A UDisksModuleObject method that is called by UDisksLinuxBlockObject, UDisksLinuxDriveObject and UDisksLinuxProvider to process a uevent on exported module objects and interfaces and control their validity.

Upon receiving a uevent the object implementing the UDisksModuleObject interface is responsible for processing updated information and indicate whether the object is still valid or not.

This function may be called quite often and since uevent processing is currently serialized by UDisksLinuxProvider this method call should minimize its processing time as much as possible.

See related udisks_module_new_object(), udisks_module_new_block_object_interface() and udisks_module_new_drive_object_interface() methods for information how uevent routing is done and what effect the return values have.

Set keep to FALSE if the object or interface should be unexported and removed, TRUE if the object or interface should be kept around. The return value of keep is ignored when the return value from this method is FALSE. These return values should align with the uevent action , i.e. a keep return value of FALSE is expected for a remove action . Note that the remove uevent is not always sent to block objects and the daemon may opt for direct object destruction (for which the object should be prepared to perform proper cleanup within its destructor).

Since: 2.0

udisks_module_object_housekeeping ()

gboolean
udisks_module_object_housekeeping (UDisksModuleObject *object,
                                   guint secs_since_last,
                                   GCancellable *cancellable,
                                   GError **error);

A UDisksModuleObject method that is called periodically (every ten minutes or so) by UDisksLinuxProvider to perform module housekeeping tasks such as refreshing ATA SMART data.

The method runs in a dedicated thread and is allowed to perform blocking I/O.

Long-running tasks should periodically check cancellable to see if they have been cancelled.

Since: 2.0

struct UDisksModule

struct UDisksModule {
};

The UDisksModule structure contains only private data and should only be accessed using the provided API.

struct UDisksModuleClass

struct UDisksModuleClass {
  GObjectClass parent_class;

  GDBusInterfaceSkeleton  * (*new_manager)                      (UDisksModule           *module);
  GDBusObjectSkeleton    ** (*new_object)                       (UDisksModule           *module,
                                                                 UDisksLinuxDevice      *device);
  gchar                   * (*track_parent)                     (UDisksModule           *module,
                                                                 const gchar            *path,
                                                                 gchar                 **uuid);
  GType                   * (*get_block_object_interface_types) (UDisksModule           *module);
  GType                   * (*get_drive_object_interface_types) (UDisksModule           *module);
  GDBusInterfaceSkeleton  * (*new_block_object_interface)       (UDisksModule           *module,
                                                                 UDisksLinuxBlockObject *object,
                                                                 GType                   interface_type);
  GDBusInterfaceSkeleton  * (*new_drive_object_interface)       (UDisksModule           *module,
                                                                 UDisksLinuxDriveObject *object,
                                                                 GType                   interface_type);
  void                      (*handle_uevent)                    (UDisksModule           *module,
                                                                 UDisksLinuxDevice      *device);
};

Class structure for UDisksModule.

UDisksModuleObject

typedef struct _UDisksModuleObject UDisksModuleObject;

The UDisksModuleObject structure contains only private data and should only be accessed using the provided API.

struct UDisksModuleObjectIface

struct UDisksModuleObjectIface {
  GTypeInterface parent_iface;

  gboolean (*process_uevent) (UDisksModuleObject  *object,
                              const gchar         *action,
                              UDisksLinuxDevice   *device,
                              gboolean            *keep);

  gboolean (*housekeeping) (UDisksModuleObject  *object,
                            guint                secs_since_last,
                            GCancellable        *cancellable,
                            GError             **error);
};

Object interface structure for UDisksModuleObject.