Presence Service D-Bus API: Difference between revisions
Jump to navigation
Jump to search
Line 58: | Line 58: | ||
* RequestRandomBuddies (u: max) → o |
* RequestRandomBuddies (u: max) → o |
||
** Request random buddies. |
|||
** Returns: |
|||
*** the view representing the result of the search. |
|||
* RequestRandomActivities (u: max) → o |
|||
** Request random buddies. |
** Request random buddies. |
||
** Returns: |
** Returns: |
Revision as of 15:19, 12 June 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
- 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
- RequestRandomBuddies (u: max) → o
- Request random buddies.
- Returns:
- the view representing the result of the search.
- RequestRandomActivities (u: max) → o
- Request random buddies.
- 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
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
BuddyView 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)