Presence Service D-Bus API

  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 (activity object path)
• ActivityDisappeared (activity object path)
• BuddyAppeared (buddy object path)
• BuddyDisappeared (buddy object path)

Methods

• GetActivities() -> ao
  • Gets all activities the PS knows about
  • Returns: array of activity object paths
• GetActivity(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.Presence.Activity
Object Path: /org/laptop/Presence/Activities/

Signals

• BuddyJoined (buddy object path)
• BuddyLeft (buddy object path)
• ServiceAppeared (service object path)
• ServiceDisappeared (service object path)

Methods

• getId()
  • Gets the activity's ID
  • Returns: string representing the activity's ID
• ownerHasJoined()
  • Returns whether or not the owner has joined this activity
  • Returns: boolean
• getServices()
  • Gets all services that exist within the scope of this activity
  • Returns: array of service object paths
• getServicesOfType(type)
  • Gets all services of a specified type that exist within the scope of this activity
  • Returns: array of service object paths
• getJoinedBuddies()
  • Gets all buddies who are currently participating in this activity
  • Returns: array of buddy object paths

Buddy Object

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

Signals

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

• IconChanged ()
• ServiceAppeared (service object path)
• ServiceDisappeared (service object path)
• JoinedActivity (activity object path)
• LeftActivity (activity object path)
• PropertyChanged (list of property names)

Methods

• getProperties()
  • 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()
  • Gets the buddy's icon pixbuf data
  • Returns: a character array containing the byte stream of the icon data
• getServiceOfType(type)
  • Gets one service of a specific type. Services must be unique within an activity, and can be "belong" to either one activity or none; but never more than one.
  • Returns: service object path, or error if no service of the requested type existed
• getJoinedActivities()
  • Gets all activities in which this buddy is currently participating
  • Returns: array of activity object paths

Channel Object

Interface: org.laptop.Presence.Channel
Object Path: /org/laptop/Presence/Channel/

Signals

• BuddyAppeared (buddy object path)
• BuddyDisappeared (buddy object path)

Methods

• getType()
  • Gets the channel's type. Only one Channel of each type may exist within an activity at any given time. Messages sent to the Channel are sent to each Buddy on the Channel, and each message sent to the Channel is received by each Buddy on the Channel. The Channel is conceptually a one-to-many communications pipe. It should be assumed that every Buddy that participates in an activity is "on" every Channel the activity provides.
  • Returns: a string representing the channel's type
• getBuddies()
  • Gets all buddies on the channel
  • Returns: array of buddy object paths

Service Object

Interface: org.laptop.Presence.Service
Object Path: /org/laptop/Presence/Services/

Signals

• PropertyChanged (list of property names)

Methods

• getProperties()
  • Gets all the service's properties
  • Returns: a dbus dict of properties (name, type, activityId, port, published address, source address, domain)
• getPublishedValue(key)
  • Gets a single value from the service's advertisement's DNS TXT record
  • Returns: the value as a dbus string