Creating plugins

Creating a source

Definition

A MAFW source is an element that can provide media information, this means available media resources over a protocol and their metadata. Accessing the media files stored in your local file system or the media served through UPnP servers are some examples.

Creating a MAFW source means creating a shared library containing a GObject that inherits from MafwSource. So what we first need to do is redefining those methods defined in MafwSourceClass.

All those methods have a default implementation in MafwSource that raise an error by default, so it is not mandatory to implement all the methods but only the ones you want to support. The most important ones are:

browse: it is used to query the source about the available media.
cancel_browse: as browse operations can take some time, this method can be called to cancel an ongoing browse operation.
get_metadata: it is used to request the metadata associated to a given media served by the source. For example, when a renderer tries to play a certain media included in a playlist, it has to obtain the URI associated to that media, this is done by calling get_metadata and passing the object identifier of the media.

Other methods are those related to creation or destruction of media items, or metadata modification. Even if your source does not need to implement these methods, it may still be interesting to provide dummy implementations so that other components that use your source do not get errors from using them. For example, a renderer may use the set_metadata method to automatically increase the playcount of a media item when played. If your source returns an error when this method is used instead of an empty implementation, the application could end up receiving that error message, which may or may not be the intended behavior.

set_metadata: sets metadata for a particular media resource.
create_object: adds a new media resource or container to the particular source.
destroy_object: removes an media item or container from a particular source.

Other than the creation of the GObject the developer has to define of a symbol containing the plugin name and three functions to initialize, refresh and deinitialize the plugin. An example of this is:

# define MAFW_SOURCE_PLUGIN_NAME "MySource-Plugin"
# define MAFW_SOURCE_NAME        "My Source"
# define MAFW_SOURCE_UUID        "mysource"


static gboolean mafw_my_source_initialize(MafwRegistry *registry,
					  GError **error);
static void mafw_my_source_refresh(GError **error);

/*
 * Registers the plugin descriptor making this plugin available to the
 * framework and applications
 */
G_MODULE_EXPORT MafwPluginDescriptor mafw_my_source_plugin_description = {
	{ .name = MAFW_LOCAL_SOURCE_PLUGIN_NAME },
	.initialize = mafw_my_source_initialize,
	.deinitialize = mafw_my_source_deinitialize,
};

/*
 * Plugin initialization. Sets UUID and name of this source and then
 * adds it to the registry
 */
static gboolean 
mafw_my_source_initialize(MafwRegistry *registry,
                          GError **error)
{
	MafwMySource *self = MAFW_MY_SOURCE(mafw_my_source_new());
	mafw_registry_add_extension(registry, MAFW_EXTENSION(self));
	g_object_unref(self);
	return TRUE;
}

/*
 * Plugin deinit
 */
static void
mafw_my_source_deinitialize(GError **error) { }

We that code we will have a module that can be recognized and loaded but we cannot forget to add the right parameters to the object constructor, otherwise the given plugin cannot be initialized:

MafwSource *mafw_local_source_new(void)
{
	return MAFW_SOURCE(g_object_new(MAFW_TYPE_LOCAL_SOURCE,
					"plugin", MAFW_LOCAL_SOURCE_PLUGIN_NAME,
					"uuid", MAFW_LOCAL_SOURCE_UUID,
					"name", MAFW_LOCAL_SOURCE_NAME,
					NULL));
}

For further details about the parameters received by functions and a deeper description of the MafwSource class, please take a look at the Mafw API reference.