Presence Service D-Bus API

PresenceService DBus API

There are 4 conceptual "objects":

• PresenceService - manages and provides a query API for Buddy, Service, and Activity objects
• Buddy - represents another laptop somewhere on the network that you can communicate with
• 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.
• Activity - represents a logical collection of services, in which one or more buddies participate. Activities are globally unique.

PresenceService Object

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

Signals

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

Methods

• 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
• 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
• 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

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

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

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