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.

There used to be more methods but the API evolved so only this single one is 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.

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