Low-level Activity API

Most activities will use the Python API to implement activities. This page will document the underlying mechanism that non-Python activities need to conform to.

This documentation effort was started by Bert while implementing the Squeak-based Etoys activity. Please fill in missing pieces and correct mistakes!

Overview

An Activity Bundle can specify an executable in the activity.info's exec field. When installing the bundle, the path of this executable will be expanded and added to the list of DBus services in $HOME/.local/share/dbus-1/services/ using the DBus service name as specified in the service_name field. When launching an activity from Sugar shell, a request to that DBus service is made, which makes DBus run the previously specified executable. The executable must create a "factory service" on the DBus using the specified service name.

The factory service provides a org.laptop.ActivityFactory.create() method which spawns an activity instance. Each activity instance has a unique activity_id which is passed as one of the parameters to the create() method.

Each activity instance opens an X window. This window must have two string properties, _SUGAR_BUNDLE_ID specifying the service name and _SUGAR_ACTIVITY_ID which is the id that was passed to create(). The instance registers a DBus object at /org/laptop/Activity/id where id is the decimal XID of the window. This object must implement the org.laptop.Activity interface.

When the last activity instance exits, the factory service should quit.

Activity Factory

Service name: my.organization.MyActivity (from activity bundle info file)

Object path: /my/organization/MyActivity (derived from service name)

Interface: org.laptop.ActivityFactory

org.laptop.ActivityFactory.create(params)

The create() method creates a new Activity instance. That instance is exposed on the DBus as /org/laptop/Activity/123456 where the number 123456 is the instance's top-level window XID.

The params dictionary can have the following entries:

activity_id

unique id for the activity to be created

pservice_id

identity of the sharing service for this activity in the PresenceService

object_id

identity of the journal object associated with the activity. When you resume an activity from the journal the object_id will be passed in (see datastore).

uri

URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages)

Activity Instance

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f (where 6f7f3acacca87886332f50bdd522d805f0abbf1f is the activity id)

Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f (where 6f7f3acacca87886332f50bdd522d805f0abbf1f is the activity id)

Interface: org.laptop.Activity

X Properties

The activity instance needs to set two properties on its top-level window:

_SUGAR_BUNDLE_ID 

The bundle id (e.g., my.organization.MyActivity) of type STRING.

_SUGAR_ACTIVITY_ID 

The activity id (e.g., 6f7f3acacca87886332f50bdd522d805f0abbf1f) of type STRING.

Methods

An activity instance needs to support the following methods:

org.laptop.Activity.share()

Called by the shell to request the activity to share itself on the network.

org.laptop.Activity.get_shared()

Returns True if the activity is shared on the mesh.

org.laptop.Activity.set_active(active)

Activate or passivate an activity. Passive activities must release resources like sound, camera etc.

org.laptop.Activity.execute(cmd, args[])

Optional - execute a command defined in the activity, answer True on success. might be deprecated soon

Datastore

An Activity instance should store its data in the central datastore so it appears in the Journal. it needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path:  /org/laptop/sugar/DataStore
Interface:    org.laptop.sugar.DataStore

An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a filename. The properties have String keys but Variant values. Here are a few properties:

'activity':          'my.organization.MyActivity'
'title':             'My Activity'
'title_set_by_user': '0' 
'keep':              '0'
'buddies':           
'preview':           base64(png file data, 300x225 px) 
'icon-color':        '#ff0000,#ffff00'
'mime_type':         'application/x-my-activity'

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename)

To update an item use update():

datastore.update(object_id, properties, filename)

To retrieve an object's properties and filename:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

Example

[Activity]
name = My Activity
activity_version = 1
host_version = 1
service_name = my.organization.MyActivity
icon = activity-my
exec = myactivityfactory
show_launcher = yes

create factory service at my.organization.MyActivity

Signal /org/freedesktop/DBus org.freedesktop.DBus.NameAcquired(':1.23')

Signal /org/freedesktop/DBus org.freedesktop.DBus.NameAcquired('my.organization.MyActivity')

MethodCall /my/organization/MyActivity org.freedesktop.DBus.Introspectable.Introspect()

MethodCall /my/organization/MyActivity org.laptop.ActivityFactory.create(activity_id='6f7f3acacca87886332f50bdd522d805f0abbf1f')

launch new activity instance

create X window with _SUGAR_BUNDLE_ID='my.organization.MyActivity' and _SUGAR_ACTIVITY_ID='6f7f3acacca87886332f50bdd522d805f0abbf1f'

create instance dbus service at org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f

Signal /org/freedesktop/DBus org.freedesktop.DBus.NameAcquired(':1.24')

Signal /org/freedesktop/DBus org.freedesktop.DBus.NameAcquired('org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f')