Presence Service D-Bus API: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
Line 13: Line 13:
Object Path: /org/laptop/Sugar/Presence<br>
Object Path: /org/laptop/Sugar/Presence<br>


===org.laptop.Sugar.Presence===
===Signals===

====Signals====
* ActivityAppeared (o: activity)
* 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
** 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
Line 26: Line 28:
** Someone has invited the user to take part in a private text conversation or VoIP call. (The platform doesn't currently handle this.)
** Someone has invited the user to take part in a private text conversation or VoIP call. (The platform doesn't currently handle this.)


===Methods===
====Methods====
* GetActivities() -> ao
* GetActivities() -> ao
** Gets all activities the PS knows about
** Gets all activities the PS knows about

Revision as of 12:34, 2 June 2008

  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
Interface: 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.)

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
  • 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

Activity Object

Interface: org.laptop.Sugar.Presence.Activity
Object Path: /org/laptop/Sugar/Presence/Activities/

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

Buddy Object

Interface: org.laptop.Sugar.Presence.Buddy
Object Path: /org/laptop/Sugar/Presence/Buddies/

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

Interface: org.laptop.Sugar.Presence.Buddy.Owner
Object Path: /org/laptop/Sugar/Presence/Buddies/

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

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