Presence Service D-Bus API

From OLPC
Revision as of 13:34, 2 August 2006 by DanWilliams (talk | contribs) (add unregisterService)
Jump to navigation Jump to search

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