Changes

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[Activity Development Alternatives]] for an overview of various ways to develop activities.

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant.  All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar.  This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant.  All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar.  This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Activity bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==

==Activity Life Cycle==

Please see [[OLPC Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''

'''Start Up'''

  org.laptop.Activity.SetActive(b: active)

  org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[OOM]]) by auto-saving to the datastore.

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

  org.laptop.Activity.Invite(s: buddy_key)

  org.laptop.Activity.Invite(s: buddy_key)

=Security=

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[Bitfrost]] and [[Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[Terminal]] activity as a maintenance tool is an exception).

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id.  That is, a new anonymous user is created when the user clicks an activity icon, and the [[Rainbow]] demon runs the activity under that user.  

Instead, each activity instance is run with a unique user id.  That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.  

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

=== Concurrency ===

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

=== External Media ===

== Signing ==

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Activity bundles#Bundle Structure|contents.sig]].

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

''to be detailed''

== Permissions Declarations ==

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See  [[Activity bundles#activity/permissions.info|permissions.info]] and generally [[Bitfrost]].

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See  [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

''to be detailed''

=Presence=

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[Activity sharing]]. The following are the bare essentials.

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

==General==

==General==

Activities must support sharing using the [[Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

  Service:    org.laptop.Sugar.Presence

  Service:    org.laptop.Sugar.Presence

===D-Bus Tubes===

===D-Bus Tubes===

''to be continued. In the mean time, see [[Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

''to be continued. In the mean time, see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

[[Category:API]]

[[Category:API]]

[[Category:Collaboration]]

[[Category:Collaboration]]