[sugar] Presence Service DBus API notes on wiki

[Dan Williams]

On Fri, 2006-07-14 at 17:52 +0200, Marco Pesenti Gritti wrote:
> - PresenceService
> 
> getBuddyByName(name)
> getBuddyByAddress(address)
> 
> These somewhat open the problems of identity... We should discuss it at 
> some point. Maybe next demo.

Quite correct.  We need to figure out a non-name-based method of
identity, and then nickname & realname become simply a property.  We
also need to make sure the address thing is IPv6 aware.

> - Buddy
> 
> getProperties()
> 
> Why not getters for each property?

Because latency sucks when you have to get each property.  We found with
NetworkManager that if you bundle up the most common properties into one
call, things go more smoothly.  Tradeoff of latency versus efficiency
here.

> getBuddyActivities()
> 
> Buddy seem somewhat redundant here. Also gives the impression the buddy 

Right; but notice that there are a _lot_ of similarly named calls for
each object.  For example, if the calls weren't verbose, the PS would
have a getActivities() call, and the buddy would have a getActivities()
call.  Similarly, all three of the PS, Buddy, and Activity objects would
each have a getServiceOfType() and a getServices() call.

I thought that would be confusing since the only difference between
these method calls is the scoping.  Better to show in the method name
exactly what's being retrieved.

> is owning these activities, while he is actually just partecipating. 
> Maybe getJoinedActivities?

Good point.  getBuddyActivities() will only ever return activities in
which the buddy is currently participating.  I should change that.

> getBuddyService(type)
> 
>  >Gets one service of a specific type. Only one service of each type may 
> be offered by each >buddy for each activity. i.e., services are unique 
> within the scope of both a buddy and an >activity
> 
> I'm a bit confused here. How this is activity scoped?

Activities "contain" services and Buddies.  It's all a bit confusing
since this is attempting to provide structure over the mDNS flat service
space.

Services may be members of an activity (Activity Chat), or they may not
be standalone (mesh chat, _presence_olpc, etc).  But a buddy may not
provide more than one type of service per activity.  In other words, its
pretty pointless to provide more than one _web_olpc service in the scope
of a single activity.  Or more than one _chat_olpc service.  Etc.

> Also Buddy is probably redundant.

See above...

> - Service
> 
> getProperties()
> getPublishedValue(key)
> 
> Is there a reason for the incosistent naming?

Well, I thought for a while about this one.  There are two "property
lists" here.  The first is the internal service properties, what we
might think of as the member variables of the object.  Those are things
like address, name, type, domain, etc.  The second are the ones that are
retrieved from the DNS TXT record after the service has been resolved.

They are distinct, and I didn't want to mix the two together.  I would
have liked to use "properties" for the TXT record ones, but I was
already using properties for the buddy object.  "Attributes" is too
generic, just like properties.  Any other suggestions here?

> - Activity
> 
> > Any comments? :)  Can you think of any operations that we currently need
> > to do that won't fit into this API?  We don't need the
> > track_service_type()/untrack_service_type() stuff since the PS will now
> > be global; though that stuff could be done in the thin Python shim that
> > we'll need to make the dbus stuff somewhat simpler.
> >   
> What is the use case of track/untrack if we have an Activity service 
> that already filter the activity specific services?

The case for track/untrack is that currently, all service announcements
will be delivered to the activity, and it's up to the activity to
determine whether or not it cares about the announcement.  That's fine,
but it's more code in the activity and slightly complicates the activity
API.  If we require activities to register the services they care about,
that code only fires _once_ (in __init__ for Python) and the filtering
would be done in the PS API bindings, rather than making the kids write
filter code for their Activity objects.  However, that means that we
have to jump through hoops (like we did with the Everyone page) in
Activities that actually do want to get all service announcements.

Maybe we can be smart about this another way.

> getActivityServices()
> getActivityServicesOfType(type)
> getActivityBuddies()
> 
> Activity seem redundant here to me.

See above...

> We need to think how to integrate presence service inside 
> sugar.activity.Activity.
> There is the name clashing between sugar.activity.Activity and 
> sugar.presence.Activity which makes things difficult. 
> sugar.presence.Activity is actually a presence service, scoped to the 
> activity. So it might be ActivityPresenceService. (GlobalPresenceService 
> and ActivityPresenceService could also implement a PresenceService 
> interfaces, but that might taking it too further).

I thought about that too; we have the local list of activities that the
Shell knows about that are running locally (ie, you have joined them
otherwise they wouldn't be running locally), and then the
PresenceService list of activities that (a) you _could_ join or (b)
already have joined.

So the PS list of activities is actually a superset of the local set of
activities that used to be kept in the shell.  Not quite sure about what
to do there.  What information do we actually need about local
activities, like what we used to keep in the shell?  Obviously the
tab-related icon & title setting stuff is gone, but what else?  What
mechanism do we use to allow the Web activity to send a link to the chat
activity like we used to do, for example?

Dan