Proposal for change notifications

["Juan A." Suárez Romero <jasuarez igalia com>]

Hello.

This is a first proposal to support notifications of changes that
happens in a plugin.

Notifications can happen because a media element has changed, or because
new content has been added or removed. In order to simplify the things,
we are more interested in the last case.

Checking the plugins we have right now, and thinking also in potential
plugins that can happen, it is true that supporting this feature heavily
depends on the support that is behind, in the backend.

Thus, we identify this 3 situations:

  * Plugins that doesn't support any kind of notification
  * Plugins that can notify that "something" changed (new content was
added, or content was removed)
  * Plugins that can notify that something changed, and more precisely,
what changed (a file has been updated) or where happened (content in a
specific folder has happened).


Based on above situations, I propose this first approach:

guint
grl_media_source_update_notify_add(GrlSource *source,
				GrlMediaSourceUpdatedCb callback,
				gpointer user_data);

void
grl_media_source_update_notify_remove(GrlSource *source,
				guint notify_id);


These operations are optional, and if plugin supports them, it should be
listed in the GrlSupportedOps (using a new flag like
GRL_OP_UPDATE_NOTIFY).

The first one installs a callback that will be invoked when a change
happens in the source.

Regarding the *_add() function, not sure if we should indicate which
element we want to monitor. I didn't consider it, but maybe it's worth
to add as parameter: if plugin can monitor a specific element, then it
can use it, else it will ignore the parameter. Plugin's documentation
should clearly state if it allows to monitor a specific folder or not.


How the notifications are sent? This is the callback signature:

typedef void
(*GrlMediaSourceUpdatedCb) (GrlMediaSource *source,
			GrlMedia *media,
			GrlMediaSourceUpdatedType type,
			gboolean include_children,
			gpointer user_data);


"media" is the media that has changed. Usually, it will be a GrlBox,
meaning that content in that box has changed. But I keep the more
generic GrlMedia just in case a plugin has the ability to specifically
notifiy that a media has changed.

We use a "media" and not the media "id" because it is expected that if
it changes, user application will perform a metadata/browse operation.
Thus it doesn't need to create the right media to do it; it already has
the changed element to use.

Also, using a GrlMedia is easy to know if content has changed (in case
it is a GrlBox) or if the property of the element has changed (in case
of GrlAudio, for instance).

"include_children" means that the media, or any of its descendants, have
changed. Of course, it only means in the (standard) case of using a
GrlBox as media.

If include_children==FALSE, it means that the box content (the direct
children) have changed. But if include_children==True then any of the
direct or indirect (children, grand-children, ...) have changed.

Thus, in the case that a plugin is only able to notify that a changed
happened in the pugin, but not where, then it can use the root box as
media, and include_children==True, meaning that "something in the root
or below has changed".

"type" indicates the kind of change. Currently, I'm only thinking on
having 3 different values:

  * GRL_UPDATE_ADDED
  * GRL_UPDATE_REMOVED
  * GRL_UPDATE_CHANGED

When something has been added and removed at the same time, the last
value would be used.

I'm not very sure if we actually need this "type" value. I've proposed
it because I was also contemplating a new kind of update: when a source
is being updated. This happens, for instance, when Tracker is updating
the content, or if a Podcasts plugin is downloading the latest clips. In
this case, a GRL_UPDATED_UPDATING signal can be used to tell it is being
updated.

Probably the case of updating could require it's own method, because it
would be good to know other information, as how many elements remains,
expected end time, and so on. But in any case, maybe we can start with
something simpler, as proposed above, and then consider a better
approach if we actually require it.