GIOModule: GIO Reference Manual

## GIOModule GIOModule — Loadable GIO Modules |

## Functions

GIOModule * | g_io_module_new ()
void | g_io_module_scope_block ()
void | g_io_module_scope_free ()
GIOModuleScope * | g_io_module_scope_new ()
GList * | g_io_modules_load_all_in_directory ()
GList * | g_io_modules_load_all_in_directory_with_scope ()
void | g_io_modules_scan_all_in_directory ()
void | g_io_modules_scan_all_in_directory_with_scope ()
void | g_io_module_load ()
void | g_io_module_unload ()
char ** | g_io_module_query ()

## Types and Values

| GIOModule
| GIOModuleScope
enum | GIOModuleScopeFlags

## Object Hierarchy

        GEnum
        ╰── GIOModuleScopeFlags
        GObject
        ╰── GTypeModule
            ╰── GIOModule

## Implemented Interfaces

GIOModule implements GTypePlugin.

## Includes

    #include <gio/gio.h>

## Description

Provides an interface and default functions for loading and unloading modules. This is used internally to make GIO extensible, but can also be used by others to implement module loading.

## Functions

### g_io_module_new ()

    GIOModule *
    g_io_module_new (const gchar *filename);

Creates a new GIOModule that will load the specific shared library when in use.

#### Parameters

filename | filename of the shared library module. | [type filename]

#### Returns

a GIOModule from given `filename` , or `NULL` on error.

### g_io_module_scope_block ()

    void
    g_io_module_scope_block (GIOModuleScope *scope,
                             const gchar *basename);

Block modules with the given `basename` from being loaded when this scope is used with `g_io_modules_scan_all_in_directory_with_scope()` or `g_io_modules_load_all_in_directory_with_scope()`.

#### Parameters

scope | a module loading scope |
basename | the basename to block |

Since: 2.30

### g_io_module_scope_free ()

    void
    g_io_module_scope_free (GIOModuleScope *scope);

Free a module scope.

#### Parameters

scope | a module loading scope |

Since: 2.30

### g_io_module_scope_new ()

    GIOModuleScope *
    g_io_module_scope_new (GIOModuleScopeFlags flags);

Create a new scope for loading of IO modules. A scope can be used for blocking duplicate modules, or blocking a module you don't want to load.

Specify the `G_IO_MODULE_SCOPE_BLOCK_DUPLICATES` flag to block modules which have the same base name as a module that has already been seen in this scope.

#### Parameters

flags | flags for the new scope |

#### Returns

the new module scope.

[transfer full]

Since: 2.30

### g_io_modules_load_all_in_directory ()

    GList *
    g_io_modules_load_all_in_directory (const gchar *dirname);

Loads all the modules in the specified directory.

If don't require all modules to be initialized (and thus registering all gtypes) then you can use `g_io_modules_scan_all_in_directory()` which allows delayed/lazy loading of modules.

#### Parameters

dirname | pathname for a directory containing modules to load. | [type filename]

#### Returns

a list of GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call `g_type_module_unuse()` on all the modules. Free the list with `g_list_free()`.

[element-type GIOModule][transfer full]

### g_io_modules_load_all_in_directory_with_scope ()

    GList *
    g_io_modules_load_all_in_directory_with_scope
                                   (const gchar *dirname,
                                    GIOModuleScope *scope);

Loads all the modules in the specified directory.

If don't require all modules to be initialized (and thus registering all gtypes) then you can use `g_io_modules_scan_all_in_directory()` which allows delayed/lazy loading of modules.

#### Parameters

dirname | pathname for a directory containing modules to load. | [type filename]
scope | a scope to use when scanning the modules. |

#### Returns

a list of GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call `g_type_module_unuse()` on all the modules. Free the list with `g_list_free()`.

[element-type GIOModule][transfer full]

Since: 2.30

### g_io_modules_scan_all_in_directory ()

    void
    g_io_modules_scan_all_in_directory (const char *dirname);

Scans all the modules in the specified directory, ensuring that any extension point implemented by a module is registered.

This may not actually load and initialize all the types in each module, some modules may be lazily loaded and initialized when an extension point it implements is used with e.g. `g_io_extension_point_get_extensions()` or `g_io_extension_point_get_extension_by_name()`.

If you need to guarantee that all types are loaded in all the modules, use `g_io_modules_load_all_in_directory()`.

#### Parameters

dirname | pathname for a directory containing modules to scan. | [type filename]

Since: 2.24

### g_io_modules_scan_all_in_directory_with_scope ()

    void
    g_io_modules_scan_all_in_directory_with_scope
                                   (const gchar *dirname,
                                    GIOModuleScope *scope);

Scans all the modules in the specified directory, ensuring that any extension point implemented by a module is registered.

This may not actually load and initialize all the types in each module, some modules may be lazily loaded and initialized when an extension point it implements is used with e.g. `g_io_extension_point_get_extensions()` or `g_io_extension_point_get_extension_by_name()`.

If you need to guarantee that all types are loaded in all the modules, use `g_io_modules_load_all_in_directory()`.

#### Parameters

dirname | pathname for a directory containing modules to scan. | [type filename]
scope | a scope to use when scanning the modules |

Since: 2.30

### g_io_module_load ()

    void
    g_io_module_load (GIOModule *module);

Required API for GIO modules to implement.

This function is run after the module has been loaded into GIO, to initialize the module. Typically, this function will call `g_io_extension_point_implement()`.

Since 2.56, this function should be named `g_io_&lt;modulename>_load`, where `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and everything after the first dot removed, and with `-` replaced with `_` throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. Using the new symbol names avoids name clashes when building modules statically. The old symbol names continue to be supported, but cannot be used for static builds.

#### Parameters

module | a GIOModule. |

### g_io_module_unload ()

    void
    g_io_module_unload (GIOModule *module);

Required API for GIO modules to implement.

This function is run when the module is being unloaded from GIO, to finalize the module.

Since 2.56, this function should be named `g_io_&lt;modulename>_unload`, where `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and everything after the first dot removed, and with `-` replaced with `_` throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. Using the new symbol names avoids name clashes when building modules statically. The old symbol names continue to be supported, but cannot be used for static builds.

#### Parameters

module | a GIOModule. |

### g_io_module_query ()

    char **
    g_io_module_query (void);

Optional API for GIO modules to implement.

Should return a list of all the extension points that may be implemented in this module.

This method will not be called in normal use, however it may be called when probing existing modules and recording which extension points that this model is used for. This means we won't have to load and initialize this module unless its needed.

If this function is not implemented by the module the module will always be loaded, initialized and then unloaded on application startup so that it can register its extension points during init.

Note that a module need not actually implement all the extension points that `g_io_module_query()` returns, since the exact list of extension may depend on runtime issues. However all extension points actually implemented must be returned by `g_io_module_query()` (if defined).

When installing a module that implements `g_io_module_query()` you must run gio-querymodules in order to build the cache files required for lazy loading.

Since 2.56, this function should be named `g_io_&lt;modulename>_query`, where `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and everything after the first dot removed, and with `-` replaced with `_` throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. Using the new symbol names avoids name clashes when building modules statically. The old symbol names continue to be supported, but cannot be used for static builds.

#### Returns

A `NULL`-terminated array of strings, listing the supported extension points of the module. The array must be suitable for freeing with `g_strfreev()`.

[transfer full]

Since: 2.24

## Types and Values

### GIOModule

    typedef struct _GIOModule GIOModule;

Opaque module base class for extending GIO.

### GIOModuleScope

    typedef struct _GIOModuleScope GIOModuleScope;

Represents a scope for loading IO modules. A scope can be used for blocking duplicate modules, or blocking a module you don't want to load.

The scope can be used with `g_io_modules_load_all_in_directory_with_scope()` or `g_io_modules_scan_all_in_directory_with_scope()`.

Since: 2.30

### enum GIOModuleScopeFlags

Flags for use with `g_io_module_scope_new()`.

#### Members

G_IO_MODULE_SCOPE_NONE | No module scan flags |
G_IO_MODULE_SCOPE_BLOCK_DUPLICATES | When using this scope to load or scan modules, automatically block a modules which has the same base basename as previously loaded module. |

Since: 2.30