Presence Service D-Bus API: Difference between revisions
Jump to navigation
Jump to search
(→Methods: added ListChannels() availability versions) |
|||
Line 70: | Line 70: | ||
*** bus name of the Telepathy connection |
*** bus name of the Telepathy connection |
||
*** object path of the Telepathy connection |
*** object path of the Telepathy connection |
||
* SearchBuddiesByProperties(a{sv}: props) → o |
|||
** Search for buddies having the given properties |
|||
** Returns: |
|||
*** the view representing the result of the search. |
|||
* SearchBuddiesByAlias(s: alias) → o |
|||
** Search for buddies having the given alias |
|||
** Returns: |
|||
*** the view representing the result of the search. |
|||
* RequestRandomBuddies (u: max) → o |
* RequestRandomBuddies (u: max) → o |
||
** Request random buddies. |
** Request random buddies. |
||
** Returns: |
|||
*** the view representing the result of the search. |
|||
* SearchActivitiesByProperties(a{sv}: props) → o |
|||
** Search for activities having the given properties |
|||
** Returns: |
** Returns: |
||
*** the view representing the result of the search. |
*** the view representing the result of the search. |
||
* RequestRandomActivities (u: max) → o |
* RequestRandomActivities (u: max) → o |
||
** Request random buddies. |
** Request for random buddies. |
||
** Returns: |
|||
*** the view representing the result of the search. |
|||
* SearchActivitiesByParticipants(au) → o |
|||
** Search for activities having the given participants. |
|||
** Returns: |
** Returns: |
||
*** the view representing the result of the search. |
*** the view representing the result of the search. |
Revision as of 09:20, 30 July 2008
This page is monitored by the OLPC team.
PresenceService D-Bus API
Revision 3 (post Collabora week)
There are 3 conceptual objects:
- PresenceService - manages and provides a query API for Activity and Buddy objects
- Activity - represents a shared space in which one or more buddies participate. Activities are globally unique.
- Buddy - represents another laptop somewhere on the network that you can communicate with
PresenceService Object
Service: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence
org.laptop.Sugar.Presence
Signals
- ActivityAppeared (o: activity)
- PS has become aware of the given activity, either because of an invitation (in which case the ActivityInvitation signal will follow soon after) or because someone is advertising it as public
- ActivityDisappeared (o: buddy)
- PS believes that the given activity has disappeared - it is not advertised as public, and either nobody has sent us a private invitation, or everyone who invited us to it has gone offline
- BuddyAppeared (o: buddy)
- BuddyDisappeared (o: buddy)
- ActivityInvitation (o: activity)
- The user has been invited to a (public or hidden) activity, represented by the given object (which might have been created immediately before).
- FIXME: as of 2007-08-28 this was documented to have parameters (o: activity, o: buddy), but the actual implementation only had one parameter?
- PrivateInvitation (s: bus_name, o: connection, o: channel)
- Someone has invited the user to take part in a private text conversation or VoIP call. (The platform doesn't currently handle this.)
- SearchAvailable ()
- Fire when PS connection becomes able to perform search
- FIXME: this is a bit cracky. Maybe we should have Connected (b: connected) signal as other part of sugar could be interested to know when we are connected (to disable share button if offline for example)
Methods
- GetActivities() -> ao
- Gets all activities the PS knows about
- Returns: array of activity object paths
- GetActivityById(s: id) -> o
- Gets a specific activity object by the activity's ID
- Returns: activity object path
- GetBuddies() -> ao
- Gets all buddies the PS knows about
- Returns: array of buddy object paths
- GetBuddyByPublicKey(ay: key) -> o
- Gets a specific buddy, searching on the buddy's public key
- Returns: the buddy object path of the requested buddy
- GetBuddyByTelepathyHandle(sou) -> o
- Get the buddy corresponding to a Telepathy handle
- Parameters:
- conn_name: The well-known bus name of a Telepathy connection
- conn_path: The object path of the Telepathy connection
- handle: The handle of a Telepathy contact on that connection, of type HANDLE_TYPE_CONTACT. This may not be a channel-specific handle
- Returns: the object path of a Buddy
- GetOwner() -> o
- Gets the owner buddy object, which is always present
- Returns: the buddy object path of the owner
- ShareActivity(s: activity id, s: activity type, s: name, a{sv}: properties) -> o
- Shares an activity with others
- As of the Trial-2 API, the activity is visible to everyone; in the Trial-3 API it will be private by default
- Returns: object path representing the new activity
- GetPreferredConnection() -> so
- Gets the preferred telepathy connection object that an activity should use when talking directly to telepathy.
- Returns:
- bus name of the Telepathy connection
- object path of the Telepathy connection
- SearchBuddiesByProperties(a{sv}: props) → o
- Search for buddies having the given properties
- Returns:
- the view representing the result of the search.
- SearchBuddiesByAlias(s: alias) → o
- Search for buddies having the given alias
- Returns:
- the view representing the result of the search.
- RequestRandomBuddies (u: max) → o
- Request random buddies.
- Returns:
- the view representing the result of the search.
- SearchActivitiesByProperties(a{sv}: props) → o
- Search for activities having the given properties
- Returns:
- the view representing the result of the search.
- RequestRandomActivities (u: max) → o
- Request for random buddies.
- Returns:
- the view representing the result of the search.
- SearchActivitiesByParticipants(au) → o
- Search for activities having the given participants.
- Returns:
- the view representing the result of the search.
Activity Object
Object Path: /org/laptop/Sugar/Presence/Activities/
org.laptop.Sugar.Presence.Activity
Signals
- BuddyJoined (o: buddy) - deprecated, see BuddyHandleJoined
- BuddyHandleJoined (o: buddy, u: handle)
- BuddyLeft (o: buddy)
- NewChannel (o: Telepathy channel)
- PropertiesChanged (a{sv}: changed properties)
- Unchanged properties are not mentioned in the dictionary
Methods
- GetId() -> s
- Gets the activity's ID. Deprecated, use GetProperties() in new code
- Returns: string representing the activity's ID
- GetColor() -> s
- Gets the activity's color. Deprecated, use GetProperties() in new code
- Returns: the activity's color in string format
- GetName() -> s
- Gets the activity's name. Deprecated, use GetProperties() in new code
- Returns: the activity's name
- GetProperties() -> a{sv}
- Get the activity properties as a dict whose keys are defined by PS. Currently the possible keys are:
- b: private (if False, advertised to all)
- s: name (title or empty string if unknown)
- s: tags (tags in some format chosen by the UI, initially empty string)
- s: color (#112233,#456789 or empty string if unknown)
- s: type (D-Bus well-known name)
- s: id (activity ID)
- Get the activity properties as a dict whose keys are defined by PS. Currently the possible keys are:
- SetProperties(a{sv}) -> nothing
- Set the properties, which are as defined by GetProperties. Unchanged properties may be omitted. The type and ID cannot be changed.
- Join() -> nothing
- Joins the activity
- Returns: nothing, or an exception on error
- Invite(o: buddy, s: message) -> nothing
- Invites the buddy, sending the message with the invitation
- Raises NotJoined, NotFound, WrongConnection or a Telepathy error on failure
- GetJoinedBuddies() -> ao
- Gets all buddies who are currently participating in this activity
- Returns: array of buddy object paths
- GetChannels() -> soao
- Gets all the Telepathy channels (chat, tube, voip, etc) belonging to this activity
- Returns:
- bus name of the Telepathy connection
- object path of the Telepathy connection
- array of Telepathy channel object paths
- ListChannels() -> soa(osuu)
- added in PS 0.81.3 (joyride-2128, 8.2-3)
- Return all the existing channels associated with this activity
- Returns:
- the D-Bus well-known service name of the connection
- the D-Bus object path of the connection
- a list of tuples containing for each channel associated with this activity:
- a D-Bus object path for the channel object
- a D-Bus interface name representing the channel type
- an integer representing the handle type this channel communicates with, or zero
- an integer handle representing the contact, room or list this channel communicates with, or zero
Buddy Object
Object Path: /org/laptop/Sugar/Presence/Buddies/
org.laptop.Sugar.Presence.Buddy
Signals
Refered objects passed in signals are specific to this buddy only.
- IconChanged (ay: icon data)
- JoinedActivity (o: activity)
- LeftActivity (o: activity)
- PropertyChanged (a{sv}: changed)
Methods
- GetProperties() -> a{sv}
- 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() -> ay
- Gets the buddy's icon data
- Returns: a character array containing the byte stream of the icon data
- GetJoinedActivities() -> ao
- Gets all activities in which this buddy is currently participating
- Returns: array of activity object paths
Owner Object
Object Path: /org/laptop/Sugar/Presence/Buddies/
Owner is a subclass of Buddy, with additional methods for setting nickname, color, and buddy icon.
org.laptop.Sugar.Presence.Buddy.Owner
Methods
- SetIcon(ay: data)
- Sets the buddy's icon data
- Returns:
- SetProperties(a{sv}: properties) -> nothing
- Sets various properties of the buddy, like nick name, color, and current activity
- Returns: InvalidPropertyError if a property is unrecognized its value is invalid
View Object
Object Path: /org/laptop/Sugar/Presence/View/
org.laptop.Sugar.Presence.View
Methods
- GetBuddies() -> ao
- Gets all buddies in this view
- Returns: array of buddy object paths
- GetActivities() -> ao
- Get all the activities in this view
- Returns: array of activities object paths
- Close() ->
- Close the view
Signals
- BuddiesChanged (ao: added, ao: removed)
- ActivitiesChanged (ao: added, ao: removed)