Extension Points

## Extension Points Extension Points — Extension Points |

## Synopsis

    #include <gio.h>

                        GIOExtension;
                        GIOExtensionPoint;
    const char *        g_io_extension_get_name             (GIOExtension *extension);
    gint                g_io_extension_get_priority         (GIOExtension *extension);
    GType               g_io_extension_get_type             (GIOExtension *extension);
    GIOExtension *      g_io_extension_point_get_extension_by_name
                                                            (GIOExtensionPoint *extension_point,
                                                             const char *name);
    GList *             g_io_extension_point_get_extensions (GIOExtensionPoint *extension_point);
    GType               g_io_extension_point_get_required_type
                                                            (GIOExtensionPoint *extension_point);
    GIOExtension *      g_io_extension_point_implement      (const char *extension_point_name,
                                                             GType type,
                                                             const char *extension_name,
                                                             gint priority);
    GIOExtensionPoint * g_io_extension_point_lookup         (const char *name);
    GIOExtensionPoint * g_io_extension_point_register       (const char *name);
    void                g_io_extension_point_set_required_type
                                                            (GIOExtensionPoint *extension_point,
                                                             GType type);
    GTypeClass *        g_io_extension_ref_class            (GIOExtension *extension);

## Description

GIOExtensionPoint provides a mechanism for modules to extend the functionality of the library or application that loaded it in an organized fashion.

An extension point is identified by a name, and it may optionally require that any implementation must by of a certain type (or derived thereof). Use `g_io_extension_point_register()` to register an extension point, and `g_io_extension_point_set_required_type()` to set a required type.

A module can implement an extension point by specifying the GType that implements the functionality. Additionally, each implementation of an extension point has a name, and a priority. Use `g_io_extension_point_implement()` to implement an extension point.

    1
    2
    3
    4
    5
    GIOExtensionPoint *ep;

    /* Register an extension point */
    ep = g_io_extension_point_register ("my-extension-point");
    g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);

    1
    2
    3
    4
    5
    6
    /* Implement an extension point */
    G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
    g_io_extension_point_implement ("my-extension-point",
                                    my_example_impl_get_type (),
                                    "my-example",
                                    10);

It is up to the code that registered the extension point how it uses the implementations that have been associated with it. Depending on the use case, it may use all implementations, or only the one with the highest priority, or pick a specific one by name.

To avoid opening all modules just to find out what extension points they implement, GIO makes use of a caching mechanism, see gio-querymodules. You are expected to run this command after installing a GIO module.

The `GIO_EXTRA_MODULES` environment variable can be used to specify additional directories to automatically load modules from. This environment variable has the same syntax as the `PATH`. If two modules have the same base name in different directories, then the latter one will be ignored. If additional directories are specified GIO will load modules from the built-in directory last.

## Details

### GIOExtension

    typedef struct _GIOExtension GIOExtension;

### GIOExtensionPoint

    typedef struct _GIOExtensionPoint GIOExtensionPoint;

### g_io_extension_get_name ()

    const char *        g_io_extension_get_name             (GIOExtension *extension);

Gets the name under which `extension` was registered.

Note that the same type may be registered as extension for multiple extension points, under different names.

`extension` : | a GIOExtension
Returns : | the name of `extension`.

### g_io_extension_get_priority ()

    gint                g_io_extension_get_priority         (GIOExtension *extension);

Gets the priority with which `extension` was registered.

`extension` : | a GIOExtension
Returns : | the priority of `extension`

### g_io_extension_get_type ()

    GType               g_io_extension_get_type             (GIOExtension *extension);

Gets the type associated with `extension`.

`extension` : | a GIOExtension
Returns : | the type of `extension`

### g_io_extension_point_get_extension_by_name ()

    GIOExtension *      g_io_extension_point_get_extension_by_name
                                                            (GIOExtensionPoint *extension_point,
                                                             const char *name);

Finds a GIOExtension for an extension point by name.

`extension_point` : | a GIOExtensionPoint
`name` : | the name of the extension to get
Returns : | the GIOExtension for `extension_point` that has the given name, or `NULL` if there is no extension with that name. [transfer none]

### g_io_extension_point_get_extensions ()

    GList *             g_io_extension_point_get_extensions (GIOExtensionPoint *extension_point);

Gets a list of all extensions that implement this extension point. The list is sorted by priority, beginning with the highest priority.

`extension_point` : | a GIOExtensionPoint
Returns : | a GList of GIOExtensions. The list is owned by GIO and should not be modified. [element-type GIOExtension][transfer none]

### g_io_extension_point_get_required_type ()

    GType               g_io_extension_point_get_required_type
                                                            (GIOExtensionPoint *extension_point);

Gets the required type for `extension_point`.

`extension_point` : | a GIOExtensionPoint
Returns : | the GType that all implementations must have, or G_TYPE_INVALID if the extension point has no required type

### g_io_extension_point_implement ()

    GIOExtension *      g_io_extension_point_implement      (const char *extension_point_name,
                                                             GType type,
                                                             const char *extension_name,
                                                             gint priority);

Registers `type` as extension for the extension point with name `extension_point_name`.

If `type` has already been registered as an extension for this extension point, the existing GIOExtension object is returned.

`extension_point_name` : | the name of the extension point
`type` : | the GType to register as extension
`extension_name` : | the name for the extension
`priority` : | the priority for the extension
Returns : | a GIOExtension object for GType. [transfer none]

### g_io_extension_point_lookup ()

    GIOExtensionPoint * g_io_extension_point_lookup         (const char *name);

Looks up an existing extension point.

`name` : | the name of the extension point
Returns : | the GIOExtensionPoint, or `NULL` if there is no registered extension point with the given name. [transfer none]

### g_io_extension_point_register ()

    GIOExtensionPoint * g_io_extension_point_register       (const char *name);

Registers an extension point.

`name` : | The name of the extension point
Returns : | the new GIOExtensionPoint. This object is owned by GIO and should not be freed. [transfer none]

### g_io_extension_point_set_required_type ()

    void                g_io_extension_point_set_required_type
                                                            (GIOExtensionPoint *extension_point,
                                                             GType type);

Sets the required type for `extension_point` to `type`. All implementations must henceforth have this type.

`extension_point` : | a GIOExtensionPoint
`type` : | the GType to require

### g_io_extension_ref_class ()

    GTypeClass *        g_io_extension_ref_class            (GIOExtension *extension);

Gets a reference to the class for the type that is associated with `extension`.

`extension` : | a GIOExtension
Returns : | the GTypeClass for the type of `extension`. [transfer full]

## See Also

Extending GIO