Presence Service D-Bus API

From OLPC
Revision as of 12:53, 21 February 2007 by 217.155.249.190 (talk) (Add bits about Owner)
Jump to navigation Jump to search
  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)

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

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
  • 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) -> nothing
    • Sets the buddy's icon data
    • Returns: nothing
  • SetProperties(a{sv}: properties)
    • Sets various properties of the buddy, like nick name, color, and current activity
    • Returns: InvalidPropertyError if the property is unrecognized