Presence Service D-Bus API

PresenceService DBus API

Revision 2

There are 5 conceptual "objects":

• PresenceService - manages and provides a query API for Activity, Buddy, Channel, and Service objects
• Activity - represents a logical collection of services, in which one or more buddies participate. Activities are globally unique.
• Buddy - represents another laptop somewhere on the network that you can communicate with
• Channel - the logical communication mechanism between buddies participating in an Activity. Each Channel exists within the context of an Activity.
• Service - represents some specific resource on the network, published by a buddy. A service may belong to either one activity or none; but never more than one activity.

PresenceService Object

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

Signals

• ActivityAppeared (activity object path)
• ActivityDisappeared (activity object path)
• BuddyAppeared (buddy object path)
• BuddyDisappeared (buddy object path)
• ServiceAppeared (service object path)
• ServiceDisappeared (service object path)

Methods

• getActivities()
  • Gets all activities the PS knows about
  • Returns: array of activity object paths
• getActivity(id)
  • Gets a specific activity
  • Returns: activity object path
• getBuddies()
  • Gets all buddies the PS knows about
  • Returns: array of buddy object paths
• getBuddyByName(name)
  • Gets a specific buddy, searching on the buddy's name
  • Returns: the buddy object path of the requested buddy, or an error if the buddy does not exist
• getBuddyByAddress(address)
  • Gets a specific buddy, searching on the buddy's IP address
  • Returns: the buddy object path of the requested buddy, or an error if the buddy does not exist
• getOwner()
  • Gets the owner buddy, representing the owner of this laptop
  • Returns: the buddy object path of the owner (always present)
• shareActivity(activityId, serviceType, properties, address, port, domain)
  • Announces an activity on the network
  • Returns: service object path representing the new share service for this 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

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