Development Team/Low-level Activity API - Revision history

Quozl: deletions and

2016-01-20T02:17:08Z

deletions and

← Older revision		Revision as of 22:17, 19 January 2016
Line 312:		Line 312:
	;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups\|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.		;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups\|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

	;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. ~~This~~ directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.		;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM if [[olpc:Rainbow\|Rainbow]] is present. It may be as small as 1 MB. With [[olpc:Rainbow\|Rainbow]], this directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

	;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming\|keeping and resuming]]). ~~This~~ directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)		;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming\|keeping and resuming]]). With [[olpc:Rainbow\|Rainbow]], this directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die).

	As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.		As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

FGrose: typo

2012-06-05T15:58:14Z

typo

← Older revision		Revision as of 11:58, 5 June 2012
Line 1:		Line 1:
	<noinclude>{{Developers~~}}{{TOCright~~}}</noinclude>		<noinclude>{{Developers}}</noinclude>__TOC__

	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.
Line 265:		Line 265:
	This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file, then call ShowObject() on it).		This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file, then call ShowObject() on it).

	Note: since Sugar 0.84, you also can give the full path to an existing file instead of an object id. If the user resumes that file, it will be copied to the Journal first and ~~the~~ opened using the chosen activity. <i>This seems to be of limited usefulness and is documented here just for completeness</i>		Note: since Sugar 0.84, you also can give the full path to an existing file instead of an object id. If the user resumes that file, it will be copied to the Journal first and then opened using the chosen activity. <i>This seems to be of limited usefulness and is documented here just for completeness</i>

	<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''		<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

Bert: /* External Media */ media -> volumes

2012-06-05T15:25:33Z

External Media: media -> volumes

← Older revision		Revision as of 11:25, 5 June 2012
Line 324:		Line 324:
	=== External Media ===		=== External Media ===

	External media (USB drives, SD cards) are auto-mounted by the Journal. No access restrictions are applied currently. If activities use these external ~~media~~ directly, they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.		External media (USB drives, SD cards) are auto-mounted by the Journal. No access restrictions are applied currently. If activities use these external volumes directly, they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

	Depending on the Linux distro version, the volumes appear as /mnt/, /media/, /run/media/$USER/*, or in other places. Sugar up to version 0.82 provided an API to access their [[#Mount Points\|mount points]]. Nowadays you should use general Linux API to find the volumes. The recommended way is using the [http://developer.gnome.org/gio/stable/GVolumeMonitor.html GNOME Volume Monitor] with a fallback to [http://www.freedesktop.org/wiki/Software/hal HAL] (there is an example in the [http://git.sugarlabs.org/backup/mainline/blobs/master/backup.py#line671 Backup activity]).		Depending on the Linux distro version, the volumes appear as /mnt/, /media/, /run/media/$USER/*, or in other places. Sugar up to version 0.82 provided an API to access their [[#Mount Points\|mount points]]. Nowadays you should use general Linux API to find the volumes. The recommended way is using the [http://developer.gnome.org/gio/stable/GVolumeMonitor.html GNOME Volume Monitor] with a fallback to [http://www.freedesktop.org/wiki/Software/hal HAL] (there is an example in the [http://git.sugarlabs.org/backup/mainline/blobs/master/backup.py#line671 Backup activity]).

Bert: /* Mount Points */ reformatting

2012-06-05T15:23:41Z

Mount Points: reformatting

← Older revision		Revision as of 11:23, 5 June 2012
Line 270:		Line 270:

	==Mount Points==		==Mount Points==
	<strike>Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.		<strike>
			Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

	mounts = datastore.mounts()		mounts = datastore.mounts()
Line 281:		Line 282:
	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).		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).

	Large files to be stored on an external device should be placed at the uri of the mount point~~</strike>~~ (see [[#External Media\|external media]]).		Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media\|external media]]).
			</strike>

	'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''		'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data. Use the [[#External Media\|external media API]] instead.''

	=Security=		=Security=

Bert: /* Presence */ presence service has been deprecated. strike out documentation.

2012-06-05T15:18:06Z

Presence: presence service has been deprecated. strike out documentation.

← Older revision		Revision as of 11:18, 5 June 2012
Line 344:		Line 344:
	''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. See [[#Collaboration\|below]] for details''		''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. See [[#Collaboration\|below]] for details''

			<strike>
	==General==		==General==

Line 398:		Line 399:
	BuddyJoined (o: buddy)		BuddyJoined (o: buddy)
	BuddyLeft (o: buddy)		BuddyLeft (o: buddy)

			</strike>

	==Tubes==		==Tubes==

Bert: /* External Media */ Recommend to use GIO to find volumes, not the deprecated mount points API

2012-06-05T15:03:24Z

External Media: Recommend to use GIO to find volumes, not the deprecated mount points API

← Older revision		Revision as of 11:03, 5 June 2012
Line 322:		Line 322:
	=== External Media ===		=== External Media ===

	External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently ~~(up to release 8.2)~~. If activities use these external media directly ~~(rather than through the Journal, see [[#Mount Points\|mount points]])~~, they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.		External media (USB drives, SD cards) are auto-mounted by the Journal. No access restrictions are applied currently. If activities use these external media directly, they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

			Depending on the Linux distro version, the volumes appear as /mnt/, /media/, /run/media/$USER/*, or in other places. Sugar up to version 0.82 provided an API to access their [[#Mount Points\|mount points]]. Nowadays you should use general Linux API to find the volumes. The recommended way is using the [http://developer.gnome.org/gio/stable/GVolumeMonitor.html GNOME Volume Monitor] with a fallback to [http://www.freedesktop.org/wiki/Software/hal HAL] (there is an example in the [http://git.sugarlabs.org/backup/mainline/blobs/master/backup.py#line671 Backup activity]).

	== Signing ==		== Signing ==

Bert: /* Mount Points */ strike out

2012-06-05T14:41:02Z

Mount Points: strike out

← Older revision		Revision as of 10:41, 5 June 2012
Line 270:		Line 270:

	==Mount Points==		==Mount Points==
	Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.		<strike>Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

	mounts = datastore.mounts()		mounts = datastore.mounts()
Line 281:		Line 281:
	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).		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).

	Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media\|external media]]).		Large files to be stored on an external device should be placed at the uri of the mount point</strike> (see [[#External Media\|external media]]).

	'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''		'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

Bert: /* Querying */ strike out mount points

2012-06-05T14:38:47Z

Querying: strike out mount points

← Older revision		Revision as of 10:38, 5 June 2012
Line 187:		Line 187:
	(results,count) = datastore.find(query, properties)		(results,count) = datastore.find(query, properties)

	It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.		It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', <strike>the mountpoint of the item at key 'mountpoint',</strike> and possibly a 'filename' if requested.

	The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.		The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.
Line 199:		Line 199:
	: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' <i>(but see note below)</i>		: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' <i>(but see note below)</i>
	: 'limit', 'offset': return only limit results starting at offset		: 'limit', 'offset': return only limit results starting at offset
	: 'mountpoints': array of [[#Mount Points\|mountpoint ids]] to search (or all if not specified)		: <strike>'mountpoints': array of [[#Mount Points\|mountpoint ids]] to search (or all if not specified) </strike>
	: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.		: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

Bert: /* Focusing Objects */ mention full file path

2012-06-05T14:27:29Z

Focusing Objects: mention full file path

← Older revision		Revision as of 10:27, 5 June 2012
Line 261:		Line 261:
	org.laptop.Journal.ShowObject(object_id)		org.laptop.Journal.ShowObject(object_id)

	Switches to the Journal activity and shows the selected object.		Switches to the Journal activity and shows the "detail view" of the selected object.

	This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file ~~in the journal~~ then call ShowObject() on it).		This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file, then call ShowObject() on it).

			Note: since Sugar 0.84, you also can give the full path to an existing file instead of an object id. If the user resumes that file, it will be copied to the Journal first and the opened using the chosen activity. <i>This seems to be of limited usefulness and is documented here just for completeness</i>

	<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''		<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

Bert: /* Choosing Objects */ remove utf8 encoding - paths are just bytes

2012-06-05T08:17:28Z

Choosing Objects: remove utf8 encoding - paths are just bytes

← Older revision		Revision as of 04:17, 5 June 2012
Line 254:		Line 254:
	ObjectChooserCancelled(chooser_id:s)		ObjectChooserCancelled(chooser_id:s)

	The chooser_id can be tested to see if this signal was in response to our own request. This is important if the user opens two file choosers at the same time (possibly in two different activities). If the user closes the chooser without selecting anything, the ObjectChooserCancelled signal is sent. Otherwise, the ObjectChooserResponse signal will be sent, and its object_id_or_path string argument is either an object id or a file path. To distinguish between the two cases, check if the first character is a slash (<tt>'/'</tt>). If it indeed begins with a slash, then this is ~~a utf8-encoded~~ absolute path to a file, which can be opened directly. Otherwise, if the first character is not a slash, then object_id_or_path is an object id, which can be used to open the corresponding [[#Keeping and Resuming\|datastore object]].		The chooser_id can be tested to see if this signal was in response to our own request. This is important if the user opens two file choosers at the same time (possibly in two different activities). If the user closes the chooser without selecting anything, the ObjectChooserCancelled signal is sent. Otherwise, the ObjectChooserResponse signal will be sent, and its object_id_or_path string argument is either an object id or a file path. To distinguish between the two cases, check if the first character is a slash (<tt>'/'</tt>). If it indeed begins with a slash, then this is an absolute path to a file, which can be opened directly. Otherwise, if the first character is not a slash, then object_id_or_path is an object id, which can be used to open the corresponding [[#Keeping and Resuming\|datastore object]].

	===Focusing Objects===		===Focusing Objects===