Presence Service D-Bus API: Difference between revisions

From OLPC
Jump to navigation Jump to search
(add newlines)
(Update some function names and add interfaces for Service, Buddy, and Activity)
Line 3: Line 3:
* PresenceService - manages and provides a query API for Buddy, Service, and Activity 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
* 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
* 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
* Activity - represents a logical collection of services, in which one or more buddies participate


Line 20: Line 20:


===Methods===
===Methods===
* getAllServices()
* getServices()
** Gets all services the PS knows about
** Gets all services the PS knows about
** Returns: array of service object paths
** Returns: array of service object paths
* getAllServicesOfType(type)
* getServicesOfType(type)
** Gets all services the PS knows about, filtered by a specific service type
** Gets all services the PS knows about, filtered by a specific service type
** Returns: array of service object paths
** Returns: array of service object paths
* getActivities()
* getAllActivities()
** 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
Line 32: Line 32:
** Gets a specific activity
** Gets a specific activity
** Returns: activity object path
** Returns: activity object path
* getAllBuddies()
* getBuddies()
** 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
Line 55: Line 55:


==Buddy Object==
==Buddy Object==
Interface: org.laptop.Presence.Buddy<br>
Object Path: /org/laptop/Presence/Buddies/<br>
Object Path: /org/laptop/Presence/Buddies/<br>


Line 72: Line 73:
** Gets the buddy's icon pixbuf data
** Gets the buddy's icon pixbuf data
** Returns: a character array containing the byte stream of the icon data
** Returns: a character array containing the byte stream of the icon data
* getBuddyService(type)
* getServiceOfType(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
** 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
** Returns: service object path, or error if no service of the requested type existed
* getJoinedActivities()
* getBuddyActivities()
** Gets all activities in which this buddy is currently participating
** Gets all activities in which this buddy is currently participating
** Returns: array of activity object paths
** Returns: array of activity object paths


==Service Object==
==Service Object==
Interface: org.laptop.Presence.Service<br>
Object Path: /org/laptop/Presence/Services/<br>
Object Path: /org/laptop/Presence/Services/<br>


Line 93: Line 95:


==Activity Object==
==Activity Object==
Interface: org.laptop.Presence.Activity<br>
Object Path: /org/laptop/Presence/Activities/<br>
Object Path: /org/laptop/Presence/Activities/<br>


Line 105: Line 108:
** Gets the activity's ID
** Gets the activity's ID
** Returns: string representing the activity's ID
** Returns: string representing the activity's ID
* haveJoined()
* ownerHasJoined()
** Returns whether or not the owner has joined this activity
** Returns whether or not the owner has joined this activity
** Returns: boolean
** Returns: boolean
* getServices()
* getActivityServices()
** Gets all services that exist within the scope of this activity
** Gets all services that exist within the scope of this activity
** Returns: array of service object paths
** Returns: array of service object paths
* getActivityServicesOfType(type)
* getServicesOfType(type)
** Gets all services of a specified type that exist within the scope of this activity
** Gets all services of a specified type that exist within the scope of this activity
** Returns: array of service object paths
** Returns: array of service object paths
* getJoinedBuddies()
* getActivityBuddies()
** Gets all buddies who are currently participating in this activity
** Gets all buddies who are currently participating in this activity
** Returns: array of buddy object paths
** Returns: array of buddy object paths

Revision as of 14:55, 17 July 2006

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

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

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)

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

(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

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