MafwRegistry

MafwRegistry — Registry for UI to find sources and renderers

Synopsis

                    MafwRegistry;
#define             MAFW_ERROR
#define             MAFW_PLUGIN_SUFFIX
enum                MafwError;
                    MafwPluginDescriptor;
                    MafwPluginDescriptorPublic;
GList*              mafw_registry_get_renderers         (MafwRegistry *self);
GList*              mafw_registry_get_sources           (MafwRegistry *self);
void                mafw_registry_add_extension         (MafwRegistry *self,
                                                         MafwExtension *extension);
void                mafw_registry_remove_extension      (MafwRegistry *self,
                                                         MafwExtension *extension);
MafwExtension*      mafw_registry_get_extension_by_uuid (MafwRegistry *self,
                                                         const gchar *uuid);
MafwRegistry*       mafw_registry_get_instance          (void);
gboolean            mafw_registry_load_plugin           (MafwRegistry *self,
                                                         const gchar *name,
                                                         GError **error);
gboolean            mafw_registry_unload_plugin         (MafwRegistry *self,
                                                         const gchar *name,
                                                         GError **error);
void                mafw_registry_load_plugins          (MafwRegistry *self);
GList*              mafw_registry_list_plugins          (MafwRegistry *self);
void                mafw_registry_unload_plugins        (MafwRegistry *self);

Object Hierarchy

  GObject
   +----MafwRegistry

Signals

  "renderer-added"                                 : Run First / Action
  "renderer-removed"                               : Run First / Action
  "source-added"                                   : Run First / Action
  "source-removed"                                 : Run First / Action

Description

MafwRegistry is the starting point for an application using the framework. It stores available renderers and sources, and provides signals for addition and removal events.

After getting a registry instance with mafw_registry_get_instance(), an application can load plugins via mafw_registry_load_plugin(), or let mafw_registry_load_plugins() load all of them residing in $MAFW_PLUGIN_DIR (see MAFW_DEFAULT_PLUGIN_DIR).

UUIDs:

Sources and renderers are identified by an arbitrary long unique string, called `Source ID' or `Renderer ID' (generally referred to as the 'uuid' of an extension). The contents have no meaning other than identifying a component. The only restriction is that it MUST NOT contain the substring "::" (that is two colons).

Currently available renderers and sources can be queried with mafw_registry_get_renderers() and mafw_registry_get_sources(), or a specific instance can be retrieved with mafw_registry_get_extension_by_uuid().

Renderer and source plugins use mafw_registry_add_extension(), and mafw_registry_remove_extension() to register or de-register their components.

Details

MafwRegistry

typedef struct _MafwRegistry MafwRegistry;

Registry instance.

MAFW_ERROR

#define MAFW_ERROR g_quark_from_static_string("com.nokia.mafw.error")

Gets a quark for general mafw error

MAFW_PLUGIN_SUFFIX

#define MAFW_PLUGIN_SUFFIX "_plugin_description"

Every plug-in should contain a MafwPluginDescriptor structure ending in this suffix.

enum MafwError

typedef enum
{
/* Plug-in loading/init related */
	MAFW_ERROR_PLUGINS_NOT_SUPPORTED,
	MAFW_ERROR_PLUGIN_LOAD_FAILED,
	MAFW_ERROR_PLUGIN_INIT_FAILED,
	MAFW_ERROR_PLUGIN_NAME_CONFLICT,
	MAFW_ERROR_PLUGIN_NOT_LOADED,
} MafwError;

General MAFW error code definitions (plug-in loading).

`MAFW_ERROR_PLUGINS_NOT_SUPPORTED`	Plug-in loading not supported.
`MAFW_ERROR_PLUGIN_LOAD_FAILED`	Loading the plug-in failed.
`MAFW_ERROR_PLUGIN_INIT_FAILED`	Error in plug-in intialization.
`MAFW_ERROR_PLUGIN_NAME_CONFLICT`	Plug-in with given name already exists.
`MAFW_ERROR_PLUGIN_NOT_LOADED`	Trying to unload a plug-in which was not loaded.

MafwPluginDescriptor

typedef struct {
        MafwPluginDescriptorPublic pub;
        gboolean (*initialize)(MafwRegistry *registry, GError **error);
        void (*deinitialize)(GError **error);
} MafwPluginDescriptor;

This structure contains all the entry points of an plugin for the framework. Every plug-in should have exactly one global instance of these, whose name is the concatenation of plugin-name and MAFW_INIT_PLUGIN_SUFFIX (e.g. "bar_plugin_descriptor").

MafwPluginDescriptorPublic `pub`;	the public part of the plugin descriptor.
`initialize` ()	After glib has been set up the framework calls this function, so the plugin can start discovering and registering its sources and renderers. By that time GType is initialized, and idle callbacks or GSources can be added to the main loop. This function should not block.
`deinitialize` ()	If not `NULL`, this function should deregister all sources and renderers of the plugin and release all claimed resources. If ever, it is called when the framework is being shut down and releasing allocated resources ensure that profiling tools (such as valgrind) won't report memory leakage after program termination.

MafwPluginDescriptorPublic

typedef struct {
        gchar const *name;
        gchar const *description;
        gchar const *version;
} MafwPluginDescriptorPublic;

Information about a plugin, returned by mafw_registry_list_plugins().

gchar const *`name`;	The human-readable name of the plugin. Not used currently, except for debugging purposes.
gchar const *`description`;	Plugin description.
gchar const *`version`;	Plugin version.

mafw_registry_get_renderers ()

GList*              mafw_registry_get_renderers         (MafwRegistry *self);

Gets the list of available renderers.

`self` :	a MafwRegistry object.
Returns :	a GList of available renderers, which should NOT be freed.

mafw_registry_get_sources ()

GList*              mafw_registry_get_sources           (MafwRegistry *self);

Gets the list of available sources.

`self` :	a MafwRegistry object.
Returns :	a GList of available sources, which should NOT be freed.

mafw_registry_add_extension ()

void                mafw_registry_add_extension         (MafwRegistry *self,
                                                         MafwExtension *extension);

Adds a MafwExtension to the registry. extension must have a UUID. There may not exist another extension of the same type with the same UUID as extension. The registry will own the reference of the added extension.

`self` :	a MafwRegistry object.
`extension` :	either a MafwRenderer or a MafwSource to be added.

mafw_registry_remove_extension ()

void                mafw_registry_remove_extension      (MafwRegistry *self,
                                                         MafwExtension *extension);

Removes a MafwExtension from the registry. extension must be registered beforehand.

`self` :	a MafwRegistry object.
`extension` :	either a MafwRenderer or a MafwSource object to remove.

mafw_registry_get_extension_by_uuid ()

MafwExtension*      mafw_registry_get_extension_by_uuid (MafwRegistry *self,
                                                         const gchar *uuid);

Gets a specific extension by its UUID. If uuid is NULL returns NULL.

`self` :	a MafwRegistry object.
`uuid` :	the UUID to be found.
Returns :	a MafwExtension object, if found or `NULL`.

mafw_registry_get_instance ()

MafwRegistry*       mafw_registry_get_instance          (void);

Unless already created, this function instantiate it from MafwRegistry. The returned object must not be unref()ed.

Returns :

the framework's Extension registry object.

mafw_registry_load_plugin ()

gboolean            mafw_registry_load_plugin           (MafwRegistry *self,
                                                         const gchar *name,
                                                         GError **error);

Loads a plug-in. It consists of two steps: finding the shared object, and the plugin descriptor structure in it.

A so-called `plugin-name' is derived from name by replacing all dashes '-' with underscores '_'. If name was an absolute filename, the above is applied to the string produced by taking the basename and removing the ".so" suffix. For example, "/tmp/my-best.so" => "my_best". The plugin-name is used to form a `plugin-symbol', by concatenating it with MAFW_PLUGIN_SUFFIX (e.g. "my_best_plugin_description"). (name should only contain alphanumeric characters, and either dashes '-' or underscores '_'.)

Note

The loaded plugin will be remembered by its plugin-name.

After we have a plugin-symbol and if name was an absolute filename, the symbol is looked up in that particular file. If it is not found, no other places are tried. On the other hand, if it was not an absolute filename, then it is searched in the following order:

in the address space of the current process
$MAFW_PLUGIN_DIR/<plugin-name>.so
let g_module_open() resolve it

The symbol should refer to a MafwPluginDescriptor structure.

`self` :	a MafwRegistry instance.
`name` :	name of the plug-in.
`error` :	location for a GError, or `NULL` if the caller is not interested.
Returns :	`TRUE` if the plug-in was loaded an initialized successfully.

mafw_registry_unload_plugin ()

gboolean            mafw_registry_unload_plugin         (MafwRegistry *self,
                                                         const gchar *name,
                                                         GError **error);

Unloads a plug-in after deinitializing it. The plugin-name is derived from name the same way as in mafw_registry_load_plugin().

`self` :	a MafwRegistry instance.
`name` :	name of the plug-in to unload.
`error` :	location for a GError, or `NULL`.
Returns :	`TRUE` on sucess on request, `FALSE` otherwise

mafw_registry_load_plugins ()

void                mafw_registry_load_plugins          (MafwRegistry *self);

Tries to load all plugins from $MAFW_PLUGIN_DIR.

self : a MafwRegistry instance.

mafw_registry_list_plugins ()

GList*              mafw_registry_list_plugins          (MafwRegistry *self);

This method gives information about the plugins this registry instance has loaded and initialized successfully.

`self` :	a MafwRegistry instance
Returns :	a list of MafwPluginDescriptorPublic structures. The caller owns the list, but may not change the list contents. The list is not kept up-to-data with changes in the list of loaded plugins and becomes invalid when one is unloaded. Free the list with `g_list_free()`.

mafw_registry_unload_plugins ()

void                mafw_registry_unload_plugins        (MafwRegistry *self);

Attempts to unload all plugins self knows about, closing their containing shared object. Successful or not all plugins will be forgotten.

self : a MafwRegistry instance.

Signal Details

The `"renderer-added"` signal

void                user_function                      (MafwRegistry *self,
                                                        MafwRenderer *renderer,
                                                        gpointer      user_data)      : Run First / Action

Emitted when a new renderer is added.

`self` :	a MafwRegistry instance.
`renderer` :	the MafwRenderer which was added.
`user_data` :	user data set when the signal handler was connected.

The `"renderer-removed"` signal

void                user_function                      (MafwRegistry *self,
                                                        MafwRenderer *renderer,
                                                        gpointer      user_data)      : Run First / Action

Emitted when a renderer is removed.

`self` :	a MafwRegistry instance.
`renderer` :	the MafwRenderer object being removed.
`user_data` :	user data set when the signal handler was connected.

The `"source-added"` signal

void                user_function                      (MafwRegistry *self,
                                                        MafwSource   *renderer,
                                                        gpointer      user_data)      : Run First / Action

Emitted when a new source is added.

`self` :	a MafwRegistry instance.
`renderer` :	the MafwSource which was added.
`user_data` :	user data set when the signal handler was connected.

The `"source-removed"` signal

void                user_function                      (MafwRegistry *self,
                                                        MafwSource   *renderer,
                                                        gpointer      user_data)      : Run First / Action

Emitted when a source is removed.

`self` :	a MafwRegistry instance.
`renderer` :	the MafwSource which is being removed.
`user_data` :	user data set when the signal handler was connected.

			MAFW Reference Manual
Top \| Description \| Object Hierarchy \| Signals

MafwRegistry

Synopsis

Object Hierarchy

Signals

Description

Details

MafwRegistry

MAFW_ERROR

MAFW_PLUGIN_SUFFIX

enum MafwError

MafwPluginDescriptor

MafwPluginDescriptorPublic

mafw_registry_get_renderers ()

mafw_registry_get_sources ()

mafw_registry_add_extension ()

mafw_registry_remove_extension ()

mafw_registry_get_extension_by_uuid ()

mafw_registry_get_instance ()

mafw_registry_load_plugin ()

Note

mafw_registry_unload_plugin ()

mafw_registry_load_plugins ()

mafw_registry_list_plugins ()

mafw_registry_unload_plugins ()

Signal Details

The "renderer-added" signal

The "renderer-removed" signal

The "source-added" signal

The "source-removed" signal

The `"renderer-added"` signal

The `"renderer-removed"` signal

The `"source-added"` signal

The `"source-removed"` signal