Presence Service D-Bus API

  This page is monitored by the OLPC team.

PresenceService D-Bus API

Revision 3 (post Collabora week)

There are 3 conceptual objects:

• PresenceService - manages and provides a query API for Activity and Buddy objects
• Activity - represents a shared space in which one or more buddies participate. Activities are globally unique.
• Buddy - represents another laptop somewhere on the network that you can communicate with

PresenceService Object

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

org.laptop.Sugar.Presence

Signals

• ActivityAppeared (o: activity)
  • PS has become aware of the given activity, either because of an invitation (in which case the ActivityInvitation signal will follow soon after) or because someone is advertising it as public
• ActivityDisappeared (o: buddy)
  • PS believes that the given activity has disappeared - it is not advertised as public, and either nobody has sent us a private invitation, or everyone who invited us to it has gone offline
• BuddyAppeared (o: buddy)
• BuddyDisappeared (o: buddy)
• ActivityInvitation (o: activity)
  • The user has been invited to a (public or hidden) activity, represented by the given object (which might have been created immediately before).
  • FIXME: as of 2007-08-28 this was documented to have parameters (o: activity, o: buddy), but the actual implementation only had one parameter?
• PrivateInvitation (s: bus_name, o: connection, o: channel)
  • Someone has invited the user to take part in a private text conversation or VoIP call. (The platform doesn't currently handle this.)

• SearchAvailable ()
  • Fire when PS connection becomes able to perform search
  • FIXME: this is a bit cracky. Maybe we should have Connected (b: connected) signal as other part of sugar could be interested to know when we are connected (to disable share button if offline for example)

Methods

• GetActivities() -> ao
  • Gets all activities the PS knows about
  • Returns: array of activity object paths

• GetActivityById(s: id) -> o
  • Gets a specific activity object by the activity's ID
  • Returns: activity object path

• GetBuddies() -> ao
  • Gets all buddies the PS knows about
  • Returns: array of buddy object paths

• GetBuddyByPublicKey(ay: key) -> o
  • Gets a specific buddy, searching on the buddy's public key
  • Returns: the buddy object path of the requested buddy

• GetBuddyByTelepathyHandle(sou) -> o
  • Get the buddy corresponding to a Telepathy handle
  • Parameters:
    • conn_name: The well-known bus name of a Telepathy connection
    • conn_path: The object path of the Telepathy connection
    • handle: The handle of a Telepathy contact on that connection, of type HANDLE_TYPE_CONTACT. This may not be a channel-specific handle
  • Returns: the object path of a Buddy

• GetOwner() -> o
  • Gets the owner buddy object, which is always present
  • Returns: the buddy object path of the owner

• ShareActivity(s: activity id, s: activity type, s: name, a{sv}: properties) -> o
  • Shares an activity with others
  • As of the Trial-2 API, the activity is visible to everyone; in the Trial-3 API it will be private by default
  • Returns: object path representing the new activity

• GetPreferredConnection() -> so
  • Gets the preferred telepathy connection object that an activity should use when talking directly to telepathy.
  • Returns:
    • bus name of the Telepathy connection
    • object path of the Telepathy connection

• SearchBuddiesByProperties(a{sv}: props) → o
  • Search for buddies having the given properties
  • Returns:
    • the view representing the result of the search.

• SearchBuddiesByAlias(s: alias) → o
  • Search for buddies having the given alias
  • Returns:
    • the view representing the result of the search.

• RequestRandomBuddies (u: max) → o
  • Request random buddies.
  • Returns:
    • the view representing the result of the search.

• SearchActivitiesByProperties(a{sv}: props) → o
  • Search for activities having the given properties
  • Returns:
    • the view representing the result of the search.

• RequestRandomActivities (u: max) → o
  • Request for random buddies.
  • Returns:
    • the view representing the result of the search.

• SearchActivitiesByParticipants(au) → o
  • Search for activities having the given participants.
  • Returns:
    • the view representing the result of the search.

Activity Object

Object Path: /org/laptop/Sugar/Presence/Activities/

org.laptop.Sugar.Presence.Activity

Signals

• BuddyJoined (o: buddy) - deprecated, see BuddyHandleJoined
• BuddyHandleJoined (o: buddy, u: handle)
• BuddyLeft (o: buddy)
• NewChannel (o: Telepathy channel)
• PropertiesChanged (a{sv}: changed properties)
  • Unchanged properties are not mentioned in the dictionary

Methods

• GetId() -> s
  • Gets the activity's ID. Deprecated, use GetProperties() in new code
  • Returns: string representing the activity's ID
• GetColor() -> s
  • Gets the activity's color. Deprecated, use GetProperties() in new code
  • Returns: the activity's color in string format
• GetName() -> s
  • Gets the activity's name. Deprecated, use GetProperties() in new code
  • Returns: the activity's name
• GetProperties() -> a{sv}
  • Get the activity properties as a dict whose keys are defined by PS. Currently the possible keys are:
    • b: private (if False, advertised to all)
    • s: name (title or empty string if unknown)
    • s: tags (tags in some format chosen by the UI, initially empty string)
    • s: color (#112233,#456789 or empty string if unknown)
    • s: type (D-Bus well-known name)
    • s: id (activity ID)
• SetProperties(a{sv}) -> nothing
  • Set the properties, which are as defined by GetProperties. Unchanged properties may be omitted. The type and ID cannot be changed.
• Join() -> nothing
  • Joins the activity
  • Returns: nothing, or an exception on error
• Invite(o: buddy, s: message) -> nothing
  • Invites the buddy, sending the message with the invitation
  • Raises NotJoined, NotFound, WrongConnection or a Telepathy error on failure
• GetJoinedBuddies() -> ao
  • Gets all buddies who are currently participating in this activity
  • Returns: array of buddy object paths
• GetChannels() -> soao
  • Gets all the Telepathy channels (chat, tube, voip, etc) belonging to this activity
  • Returns:
    • bus name of the Telepathy connection
    • object path of the Telepathy connection
    • array of Telepathy channel object paths

• ListChannels() -> soa(osuu)
  • added in PS 0.81.3 (joyride-2128, 8.2-3)
  • Return all the existing channels associated with this activity
  • Returns:
    • the D-Bus well-known service name of the connection
    • the D-Bus object path of the connection
    • a list of tuples containing for each channel associated with this activity:
      • a D-Bus object path for the channel object
      • a D-Bus interface name representing the channel type
      • an integer representing the handle type this channel communicates with, or zero
      • an integer handle representing the contact, room or list this channel communicates with, or zero

Buddy Object

Object Path: /org/laptop/Sugar/Presence/Buddies/

org.laptop.Sugar.Presence.Buddy

Signals

Refered objects passed in signals are specific to this buddy only.

• IconChanged (ay: icon data)
• JoinedActivity (o: activity)
• LeftActivity (o: activity)
• PropertyChanged (a{sv}: changed)

Methods

• GetProperties() -> a{sv}
  • Gets all the general properties of the buddy
  • Returns: a dbus dict of buddy properties, like nickname, realname, IP address, whether or not this buddy is the laptop owner, etc
• GetIcon() -> ay
  • Gets the buddy's icon data
  • Returns: a character array containing the byte stream of the icon data
• GetJoinedActivities() -> ao
  • Gets all activities in which this buddy is currently participating
  • Returns: array of activity object paths

Owner Object

Object Path: /org/laptop/Sugar/Presence/Buddies/

Owner is a subclass of Buddy, with additional methods for setting nickname, color, and buddy icon.

org.laptop.Sugar.Presence.Buddy.Owner

Methods

• SetIcon(ay: data)
  • Sets the buddy's icon data
  • Returns:
• SetProperties(a{sv}: properties) -> nothing
  • Sets various properties of the buddy, like nick name, color, and current activity
  • Returns: InvalidPropertyError if a property is unrecognized its value is invalid

View Object

Object Path: /org/laptop/Sugar/Presence/View/

org.laptop.Sugar.Presence.View

Methods

• GetBuddies() -> ao
  • Gets all buddies in this view
  • Returns: array of buddy object paths

• GetActivities() -> ao
  • Get all the activities in this view
  • Returns: array of activities object paths

• Close() ->
  • Close the view

Signals

• BuddiesChanged (ao: added, ao: removed)
• ActivitiesChanged (ao: added, ao: removed)