UDisksModuleManager: UDisks Reference Manual

## UDisksModuleManager UDisksModuleManager — Manage daemon modules |

## Functions

UDisksModuleManager * | udisks_module_manager_new ()
UDisksModuleManager * | udisks_module_manager_new_uninstalled ()
gboolean | udisks_module_manager_load_single_module ()
void | udisks_module_manager_load_modules ()
void | udisks_module_manager_unload_modules ()
GList * | udisks_module_manager_get_modules ()
UDisksDaemon * | udisks_module_manager_get_daemon ()
gboolean | udisks_module_manager_get_uninstalled ()

## Types and Values

| UDisksModuleManager

## Description

#### UDisks modular approach

UDisks functionality can be extended by modules. It's not that traditional fully pluggable system as we all know it, modules are essentially just carved-out parts of the daemon code and are free to access whatever internal daemon objects they need. There's no universal module API other than a couple of module initialization functions and a stateful module object. Out-of-tree modules are not supported either and no ABI guarantee exists at all.

This fact allows us to stay code-wise simple and transparent. It's also easier to adapt modules for any change done to the core daemon. As a design decision and leading from GType system limitation modules can't be unloaded once initialized. This may be a subject to change in the future, though unlikely.

The primary motivation for introducing the modular system was to keep the daemon low on resource footprint for basic usage (typically desktop environments) and activating extended functionality only as needed (e.g. enterprise storage applications). As the extra information comes in form of additional D-Bus objects and interfaces, no difference should be observed by ordinary clients.

#### Modules activation

The UDisks daemon constructs a UDisksModuleManager singleton acting as a module manager. This object tracks module usage and takes care of their activation.

By default UDisksModuleManager is constructed on daemon startup with module loading delayed until requested. This can be overridden by the `--force-load-modules` and `--disable-modules` commandline switches that makes modules loaded right on startup or never loaded respectively.

Clients are supposed to call the org.freedesktop.UDisks2.Manager.EnableModule() D-Bus method as a "greeter" call for each module requested. Proper error is reported should the module initialization fail or the module is not available. Clients are supposed to act accordingly and make sure that all requested modules are available and loaded prior to using any of the extra API.

Upon successful activation, a `modules-activated` signal is emitted internally on the UDisksModuleManager object. Any daemon objects connected to this signal are responsible for performing "coldplug" on exported objects to assure modules would pick up the devices they're interested in.

#### D-Bus interface extensibility

The modular approach is fairly simple, there are basically three primary ways of extending the D-Bus API:

- by attaching custom interfaces to existing block and drive objects - see `udisks_module_new_block_object_interface()` and `udisks_module_new_drive_object_interface()`.

- by exporting objects of its own type (socalled "module objects") directly on the object manager root - see `udisks_module_new_object()`.

- attaching a common manager interface on the master `/org/freedesktop/UDisks2/Manager` object - see `udisks_module_new_manager()`.

All these ways of extensibility are implemented as UDisksModule methods and it is a UDisksModuleManager task to provide interconnection between UDisksModule instances and daemon objects representing drives and block devices.

## Functions

### udisks_module_manager_new ()

    UDisksModuleManager *
    udisks_module_manager_new (UDisksDaemon *daemon);

Creates a new UDisksModuleManager object.

#### Parameters

daemon | A UDisksDaemon instance. |

#### Returns

A UDisksModuleManager. Free with `g_object_unref()`.

### udisks_module_manager_new_uninstalled ()

    UDisksModuleManager *
    udisks_module_manager_new_uninstalled (UDisksDaemon *daemon);

Creates a new UDisksModuleManager object with indication that the daemon runs from a source tree.

#### Parameters

daemon | A UDisksDaemon instance. |

#### Returns

A UDisksModuleManager. Free with `g_object_notify()`.

### udisks_module_manager_load_single_module ()

    gboolean
    udisks_module_manager_load_single_module
                                   (UDisksModuleManager *manager,
                                    const gchar *name,
                                    GError **error);

Loads single module and emits the `modules-activated` signal in case the module activation was successful. Already active module is not being reinitialized on subsequent calls to this method and `TRUE` is returned immediately.

#### Parameters

manager | A UDisksModuleManager instance. |
name | Module name. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if module was activated successfully, `FALSE` otherwise with `error` being set.

### udisks_module_manager_load_modules ()

    void
    udisks_module_manager_load_modules (UDisksModuleManager *manager);

Loads all modules at a time and emits the `modules-activated` signal in case any new module has been activated. Modules that are already loaded are skipped on subsequent calls to this method.

#### Parameters

manager | A UDisksModuleManager instance. |

### udisks_module_manager_unload_modules ()

    void
    udisks_module_manager_unload_modules (UDisksModuleManager *manager);

Unloads all modules at a time. A `modules-activated` signal is emitted if there are any modules staged for unload to give listeners room to unexport all module interfaces and objects. The `udisks_module_manager_get_modules()` would return `NULL` at that time. Note that proper module unload is not fully supported, this is just a convenience call for cleanup.

#### Parameters

manager | A UDisksModuleManager instance. |

### udisks_module_manager_get_modules ()

    GList *
    udisks_module_manager_get_modules (UDisksModuleManager *manager);

Gets list of active modules. Can be called from different threads.

#### Parameters

manager | A UDisksModuleManager instance. |

#### Returns

A list of UDisksModule or `NULL` if no modules are presently loaded. Free the elements with `g_object_unref()`.

[transfer full][nullable][element-type UDisksModule]

### udisks_module_manager_get_daemon ()

    UDisksDaemon *
    udisks_module_manager_get_daemon (UDisksModuleManager *manager);

Gets the daemon used by `manager` .

#### Parameters

manager | A UDisksModuleManager. |

#### Returns

A UDisksDaemon. Do not free, the object is owned by `manager` .

### udisks_module_manager_get_uninstalled ()

    gboolean
    udisks_module_manager_get_uninstalled (UDisksModuleManager *manager);

Indicates whether the udisks daemon runs from a source tree rather than being a regular system instance.

#### Parameters

manager | A UDisksModuleManager. |

#### Returns

`TRUE` when the daemon runs from a source tree, `FALSE` otherwise.

## Types and Values

### UDisksModuleManager

    typedef struct _UDisksModuleManager UDisksModuleManager;

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