Presence Service D-Bus API: Difference between revisions
Jump to navigation
Jump to search
DanWilliams (talk | contribs) (Add PropertyChanged signals to Buddy and Service objects) |
DanWilliams (talk | contribs) (add unregisterService) |
||
Line 53: | Line 53: | ||
** Announces the availability of a non-Activity-related service. Low level and should not generally be used unless really needed. |
** 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 |
** 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== |
==Buddy Object== |
Revision as of 13:34, 2 August 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. 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