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 is basically a regular X11 program which communicates with the special Sugar services via DBus.

The Activity Bundle specifies an executable. For each activity instance, that executable is run with arguments specifying the bundle id (taken from the bundle) and actvity id (generated by Sugar). The instance opens an X window, putting these ids into window properties. It also needs to provide a DBus service to receive messages from Sugar. An activity must retrieve and store its state in the datastore and implement sharing on the mesh network.

Activity Instance

When the activity instance is executed, then current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity). Also, its "bin" subdirectory is added to the PATH. The following arguments are passed to the executable:

-b, --bundle-id

Identifier of the activity bundle

-a, --activity-id

Unique identifier of the activity instance.

-o, --object-id

(optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see datastore).

-u, --uri

(optional) 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).

X Properties

The activity instance needs to set some 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.

This properties must to set before the window is showed on the screen, using the gtk realize event, for example.

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See Freedesktop specification.

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See Freedesktop specification.

DBus Methods

An activity instance needs to create a DBus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f
Object path:  /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface:    org.laptop.Activity

(where 6f7f3acacca87886332f50bdd522d805f0abbf1f is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(active)

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

org.laptop.Activity.TakeScreenshot()

Hint to the activity that it might be a good idea to take a preview screenshot now, because its window is going to be obscured as soon as the method returns (e.g., by the frame). Should not take more than 0.1 seconds.

There used to be more methods but the API evolved so only these are remaining for now.

Datastore

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. 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

Keeping and Resuming

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

'activity':          'my.organization.MyActivity'
'activity_id':       '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title':             'My new project'
'title_set_by_user': '0' 
'keep':              '0'
'ctime':             '1972-05-12T18:41:08'                    #created
'mtime':             '2007-06-16T03:42:33'                    #modified
'timestamp':         1192715145                               #modified in seconds since the UNIX epoch
'buddies':           array of buddies                         #not spec'ed yet
'preview':           ByteArray(png file data, 300x225 px)
'icon-color':        '#ff0000,#ffff00'
'mime_type':         'application/x-my-activity'
'summary:text':      'text I want to be indexed'              #properties with key ending in ":text" will be searched in fulltext search

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

object_id = datastore.create(properties, filename)

If filename is not empty, the file will be copied to the datastore. The activity should delete the file once the call completes. The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename)

Again, if a filename was given, it should be deleted when the call returns.

To retrieve an object's properties and file:

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

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

Querying

Activities may query the datastore:

(results,count) = datastore.find(query)

It returns the results as array of properties and a count of matching items (the array may have less items if the query was limited). In addition to the usual metadata items, the properties will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The query can be a:

string: fulltext search

the given string is searched in all text properties

dictionary: structured query

the key-value pairs in the dictionary specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:

'title' = 'First Project'

'mime_type' = ['image/png', 'image/jpeg']

'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}

also, there are a few specific keys to adjust the query:

'query': fulltext search term

'order_by': key (or array of keys) to order results by, to reverse order use '-key'

'limit', 'offset': return only limit results starting at offset

'mountpoints': array of mountpoint ids to search (or all if not specified)

'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

Note that currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries.

Mount Points

Devices are represented as mount points in the datastore. If no mountpoint is explicitely specified, the main datastore (Journal) is used.

  mounts = datastore.mounts()

Returns an array of mount point descriptiors where each descriptor is a dictionary containing at least the following keys:

'id': the id used to refer explicitly to the mount point

'title': Human readable identifier for the mountpoint

'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Presence

Activities must support sharing using the Presence Service (PS). It is accessible on the DBus:

Service:     org.laptop.Sugar.Presence
Interface:   org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

Joining

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

Sharing

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). Properties is a dictionary of arbitrary meta data (string-value pairs). Significant keys include:

'private': false                                       # if False, advertised to all
'name':    'My new project'                            # shown in mesh view
'tags':    'tag1,tag2'
'color':   '#ff0000,#ffff00'
'type':    'my.organization.MyActivity'                # bundle id
'id':      '6f7f3acacca87886332f50bdd522d805f0abbf1f'  # activity id

Communication

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. For example, the meta data can be accessed in either instance:

props = activity.GetProperties()

to be continued. For more details, see Presence Service DBus API.

Example

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

launch new activity instance by running the myactivity command

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

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')