Presence Service D-Bus API

From OLPC
Revision as of 04:11, 14 July 2006 by 66.92.78.209 (talk) (→‎Methods: add methods for sharing activities and registering services)
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
  • Activity - represents a logical collection of services, in which one or more buddies participate

PresenceService Object

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

  • getAllServices()
    • Gets all services the PS knows about
    • Returns: array of service object paths
  • getAllServicesOfType(type)
    • Gets all services the PS knows about, filtered by a specific service type
    • Returns: array of service object paths
  • getAllActivities()
    • Gets all activities the PS knows about
    • Returns: array of activity object paths
  • getActivity(id)
    • Gets a specific activity
    • Returns: activity object path
  • getAllBuddies()
    • 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

Buddy Object

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)

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
  • getBuddyService(type)
    • Gets one service of a specific type. Only one service of each type may be offered by each buddy for each activity. i.e., services are unique within the scope of both a buddy and an activity
    • Returns: service object path, or error if no service of the requested type existed
  • getBuddyActivities()
    • Gets all activities in which this buddy is currently participating
    • Returns: array of activity object paths

Service Object

Signals

(none)

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

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
  • getActivityServices()
    • Gets all services that exist within the scope of this activity
    • Returns: array of service object paths
  • getActivityServicesOfType(type)
    • Gets all services of a specified type that exist within the scope of this activity
    • Returns: array of service object paths
  • getActivityBuddies()
    • Gets all buddies who are currently participating in this activity
    • Returns: array of buddy object paths