Presence Service D-Bus API: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
|||
(10 intermediate revisions by 4 users not shown) | |||
Line 26: | Line 26: | ||
* PrivateInvitation (s: bus_name, o: connection, o: channel) |
* 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.) |
** 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==== |
====Methods==== |
||
Line 35: | Line 31: | ||
** 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 |
||
* GetActivityById(s: id) -> o |
* GetActivityById(s: id) -> o |
||
** Gets a specific activity object by the activity's ID |
** Gets a specific activity object by the activity's ID |
||
** Returns: activity object path |
** Returns: activity object path |
||
* GetBuddies() -> ao |
* GetBuddies() -> ao |
||
** 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 |
||
* GetBuddyByPublicKey(ay: key) -> o |
* GetBuddyByPublicKey(ay: key) -> o |
||
** Gets a specific buddy, searching on the buddy's public key |
** Gets a specific buddy, searching on the buddy's public key |
||
** Returns: the buddy object path of the requested buddy |
** 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 |
* GetOwner() -> o |
||
** Gets the owner buddy object, which is always present |
** Gets the owner buddy object, which is always present |
||
** Returns: the buddy object path of the owner |
** Returns: the buddy object path of the owner |
||
* ShareActivity(s: activity id, s: activity type, s: name, a{sv}: properties) -> o |
* ShareActivity(s: activity id, s: activity type, s: name, a{sv}: properties) -> o |
||
** Shares an activity with others |
** 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 |
** 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 |
** Returns: object path representing the new activity |
||
* GetPreferredConnection() -> so |
* GetPreferredConnection() -> so |
||
** Gets the preferred telepathy connection object that an activity should use when talking directly to telepathy. |
** Gets the preferred telepathy connection object that an activity should use when talking directly to telepathy. |
||
Line 56: | Line 66: | ||
*** bus name of the Telepathy connection |
*** bus name of the Telepathy connection |
||
*** object path of the Telepathy connection |
*** object path of the Telepathy connection |
||
* RequestRandomBuddies (u: max) → o |
|||
** Request random buddies. |
|||
⚫ | |||
*** the view representing the result of the search. |
|||
==Activity Object== |
==Activity Object== |
||
Line 109: | Line 114: | ||
*** object path of the Telepathy connection |
*** object path of the Telepathy connection |
||
*** array of Telepathy channel object paths |
*** 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 |
|||
⚫ | |||
*** 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== |
==Buddy Object== |
||
Line 145: | Line 162: | ||
** Sets various properties of the buddy, like nick name, color, and current activity |
** Sets various properties of the buddy, like nick name, color, and current activity |
||
** Returns: InvalidPropertyError if a property is unrecognized its value is invalid |
** Returns: InvalidPropertyError if a property is unrecognized its value is invalid |
||
==BuddyView Object== |
|||
Object Path: /org/laptop/Sugar/Presence/View/<br> |
|||
===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) |
|||
[[Category:Sugar]] |
[[Category:Sugar]] |
Latest revision as of 16:30, 22 October 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.)
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
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