Presence Service D-Bus API

From OLPC
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
  This page is monitored by the OLPC team.

PresenceService DBus 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

Signals

  • ActivityAppeared (o: activity)
  • ActivityDisappeared (o: buddy)
  • BuddyAppeared (o: buddy)
  • BuddyDisappeared (o: buddy)
  • ActivityInvitation (o: activity)
  • PrivateInvitation (s: bus_name, o: connection, o: channel)

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
    • 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)
  • BuddyLeft (o: buddy)
  • NewChannel (o: Telepathy channel)

Methods

  • GetId() -> s
    • Gets the activity's ID
    • Returns: string representing the activity's ID
  • GetColor() -> s
    • Gets the activity's color
    • Returns: the activity's color in string format
  • GetName() -> s
    • Gets the activity's name
    • Returns: the activity's name
  • GetType() -> s
    • Gets the activity's type
    • Returns: the activity's type
  • Join() -> nothing
    • Joins the activity
    • Returns: nothing, or an exception on error
  • 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: nothing
  • 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