Presence Service D-Bus API: Difference between revisions

From OLPC
Jump to navigation Jump to search
(start cleaning up the API in preparation for telepathy goodness)
(Fix up the PS object spec)
Line 20: Line 20:


===Methods===
===Methods===
* GetActivities()
* GetActivities() -> ao
** Gets all activities the PS knows about
** Gets all activities the PS knows about
** Returns: array of activity object paths
** Returns: array of activity object paths
* GetActivity(id)
* GetActivity(s: id) -> o
** Gets a specific activity
** Gets a specific activity object by the activity's ID
** Returns: activity object path
** Returns: activity object path
* GetBuddies()
* GetBuddies() -> ao
** Gets all buddies the PS knows about
** Gets all buddies the PS knows about
** Returns: array of buddy object paths
** Returns: array of buddy object paths
* GetBuddyByPublicKey()
* GetBuddyByPublicKey(ay: key) -> o
** Gets a specific buddy, searching on the buddy's name
** Gets a specific buddy, searching on the buddy's public key
** Returns: the buddy object path of the requested buddy, or an error if the buddy does not exist
** Returns: the buddy object path of the requested buddy
* GetOwner()
* GetOwner() -> o
** Gets the owner buddy, representing the owner of this laptop
** Gets the owner buddy object, which is always present
** Returns: the buddy object path of the owner (always present)
** Returns: the buddy object path of the owner
* ShareActivity(activityId, serviceType, properties, address, port, domain)
* ShareActivity(s: activity id, s: activity type, s: name, a{sv}: properties) -> o
** Announces an activity on the network
** Shares an activity with others
** Returns: service object path representing the new share service for this activity
** Returns: object path representing the new activity
* joinActivity(activity object path, serviceType)
** given a known activity and activity's flagship service type, announce that this laptop has joined a particular activity
** Returns: success or failure as a boolean
* getServices()
** Gets all services the PS knows about
** Returns: array of service object paths
* getServicesOfType(type)
** Gets all services the PS knows about, filtered by a specific service type
** Returns: array of service object paths
* registerService(name, serviceType, properties, address, port, domain)
** Announces the availability of a non-Activity-related service. Low level and should not generally be used unless really needed.
** Returns: service object path representing the new service
* unregisterService(service object path)
** Unregisters the non-Activity-related service, notifying others that this service is no longer provided by this laptop. Low level and should not generally be used unless really needed.
** Returns: nothing



==Activity Object==
==Activity Object==

Revision as of 17:28, 20 February 2007

  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
Retrieved from "http://wiki.laptop.org/mediawiki/index.php?title=Presence_Service_D-Bus_API&oldid=25405"