Re: Proposal for change notifications

[Iago Toral <itoral igalia com>]

On Wed, 19 Jan 2011 13:57:16 +0100, "Juan A." Suárez Romero 
<jasuarez igalia com> wrote:
> On Wed, 2011-01-19 at 13:01 +0100, Iago Toral Quiroga wrote:
> > > 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.
> >
> > I have some doubts here. Let's discuss this proposal over a specific
> > example: let's say I copy a new file and Tracker indexes it. The 
> > plugin
> > would invoke the notify callback with the parent folder... but what 
> > is
> > that parent folder? for sources that do not implement browse, this 
> > does
> > not even make sense! We could be interested in notify signals even 
> > if
> > the source is only searchable, right?
>
> If the direct parent folder can be obtained, then the root one should 
> be
> used, and include_children set to True. IMHO, if the source doesn't
> implement browse() it should always use this approach, even if it 
> knows
> to compute a parent box for the changed elements, because we do not
> support search in specific folder.
>
> If I, as application developer, are only interested in results 
> obtained
> with a search, everytime I get a notification, if media is a 
> GrlBox[1],
> no matter if it is a root or any other folder, or the value of
> include_children: I will perform a new search.
>
> The value of the box and include_children is only interested for the
> cases where a browse is supported: I need to know if a new browse 
> must
> be done or not.

Ok, so we have these cases:

1) A bunch of new items have been added (or removed)

The callback comes with the some ancestor GrlBox object that is common 
to all objects changed or it invokes notify various times with all the 
affected GrlBox objects. That would be decided by the plugin developer, 
right? although our advise should be to do just one notify at the end of 
the process. If the plugin does not support browse, a root GrlMedia 
object is provided (NULL id).

The client would have to check if that GrlBox (or maybe one of its 
children, depending on the include_children param)  is being showed in 
the UI and in that case it would refresh (=> repeat the browse 
operation). The client can use the GrlMedia id for this check although 
for the children case it would probably needs some extra work on the UI 
side I guess.

If the client is only interested in search(), it would ignore the 
parent GrlMedia parameter and would repeat the search in any case.

2) One specific media has changed

The callback would be invoked with the specific GrlMedia object whose 
properties have changed. If the user is showing information about that 
media, then it could refresh the UI after a metadata() operation. The 
user could do this check using the GrlMedia id.

I guess this covers all the cases...

> > > "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".
> >
> > The idea looks good to me, but I dislike the 'include_children' 
> > name.
> > What about 'change_location_unknown'? Also, again, we chould check 
> > how
> > this works with searchable-only plugins.
>
> To be honest, I didn't like it very much :) But I couldn't get a 
> better
> name.
>
> I'd use 'location_unknown', shorter, and we already know we are 
> talking
> about changes.

Ok.

> Regarding searchable-only plugins, I would use in that case the root
> GrlBox and location_unknown==True. Which means 'something changed in 
> the
> plugin'.

Ok.

(...)
> > > 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.
> >
> > Yeah, probably when a source is being updated it should wait until 
> > it
> > has finished before signaling anything. In that case it could emit a
> > bunch of ADDED / REMOVED notifications or just a single CHANGED.
>
> Yes, I would emit first the GRL_UPDATE_UPDATING and finally
> GRL_UPDATE_CHANGED to notify user that something changed.
>
> We need to take in care that a change can happen in a file without
> actually changing its properties. Even in this case a notification
> should be emitted. But I'm not sure if it would be worth to have a
> different change flag to notify that though it has changed, no need 
> to
> perform a new browse() nor metadata() is required, because properties
> have not changed. I would forget about it right now.

Not sure about this case, but I agree we can consider it later on.

Iago