Extension Points

Extension Points — Extension Points

Functions

Types and Values

Includes

#include <gio.h>

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 be 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.

Functions

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

extension

a GIOExtension

 

Returns

the GTypeClass for the type of extension .

[transfer full]

Types and Values

GIOExtension

typedef struct _GIOExtension GIOExtension;

GIOExtension is an opaque data structure and can only be accessed using the following functions.


GIOExtensionPoint

typedef struct _GIOExtensionPoint GIOExtensionPoint;

GIOExtensionPoint is an opaque data structure and can only be accessed using the following functions.

See Also

Extending GIO