Creating plugins

Creating a source
Definition
Creating a renderer
Definition
Signals
Other issues
Properties

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 and provide an implementation for some of the methods defined in that class.

All the 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:

  • mafw_source_browse: it is used to query the source about the available media.

  • mafw_source_cancel_browse: mafw_source_browse operations can take some time, so this method is intended to cancel ongoing browse operations.

  • mafw_source_get_metadata: it is used to request the metadata associated to a given media served by a 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 the source do not get errors then using these services. For example, a renderer may use the mafw_source_set_metadata method to automatically increase the play-count of media items when played. If a source returns an error when this method is invoked instead of of providing an empty implementation, the application could end up receiving that error message or the renderer may abort the playback operation, which may or may not be the intended behaviors.

  • mafw_source_set_metadata: Sets metadata for a particular media resource.

  • mafw_source_create_object: Adds a new media resource or container to a particular source.

  • mafw_source_destroy_object: Removes a media item or container from a particular source.

Other than creating a GObject the developer has to define a symbol containing the plugin name and functions to initialize 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_deinitialize(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_MY_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, making it available to applications.
 */
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));
	return TRUE;
}

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

The code above shows a plugin that can be recognized and loaded. The mafw_my_source_initialize function creates an instance of the source by using the object constructor method, and registers the source in the registry, making it available to applications.

MafwSource *mafw_my_source_new(void)
{
	return MAFW_MY_SOURCE(g_object_new(MAFW_TYPE_MY_SOURCE,
					"plugin", MAFW_MY_SOURCE_PLUGIN_NAME,
					"uuid", MAFW_MY_SOURCE_UUID,
					"name", MAFW_MY_SOURCE_NAME,
					NULL));
}
      

Notice that the plugin initialization function may instantiate and register several objects (sources in this case). For example, a UPnP plugin may check for available UPnP servers and register a source object per server discovered.

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.