Presence Service D-Bus API: Difference between revisions
Jump to navigation
Jump to search
(Add bits about Owner) |
No edit summary |
||
(45 intermediate revisions by 13 users not shown) | |||
Line 1: | Line 1: | ||
{{OLPC}} |
{{OLPC}} |
||
=PresenceService |
=PresenceService D-Bus API= |
||
<b>Revision 3 (post Collabora week)</b><br> |
<b>Revision 3 (post Collabora week)</b><br> |
||
Line 10: | Line 10: | ||
==PresenceService Object== |
==PresenceService Object== |
||
Service: org.laptop.Sugar.Presence<br> |
Service: org.laptop.Sugar.Presence<br> |
||
⚫ | |||
Object Path: /org/laptop/Sugar/Presence<br> |
Object Path: /org/laptop/Sugar/Presence<br> |
||
⚫ | |||
⚫ | |||
⚫ | |||
* ActivityAppeared (o: activity) |
* 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) |
* 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) |
* BuddyAppeared (o: buddy) |
||
* BuddyDisappeared (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=== |
====Methods==== |
||
* GetActivities() -> ao |
* GetActivities() -> ao |
||
** 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 |
|||
** Returns: object path representing the new activity |
** 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== |
==Activity Object== |
||
⚫ | |||
Object Path: /org/laptop/Sugar/Presence/Activities/<br> |
Object Path: /org/laptop/Sugar/Presence/Activities/<br> |
||
⚫ | |||
===Signals=== |
====Signals==== |
||
* BuddyJoined (o: buddy) |
|||
* ''BuddyJoined (o: buddy) - deprecated, see BuddyHandleJoined'' |
|||
* BuddyHandleJoined (o: buddy, u: handle) |
|||
* BuddyLeft (o: buddy) |
* BuddyLeft (o: buddy) |
||
* NewChannel (o: Telepathy channel) |
* NewChannel (o: Telepathy channel) |
||
* PropertiesChanged (a{sv}: changed properties) |
|||
** Unchanged properties are not mentioned in the dictionary |
|||
===Methods=== |
====Methods==== |
||
* GetId() -> s |
* GetId() -> s |
||
** Gets the activity's ID |
** Gets the activity's ID. Deprecated, use GetProperties() in new code |
||
** Returns: string representing the activity's ID |
** Returns: string representing the activity's ID |
||
* GetColor() -> s |
* GetColor() -> s |
||
** Gets the activity's color |
** Gets the activity's color. Deprecated, use GetProperties() in new code |
||
** Returns: the activity's color in string format |
** Returns: the activity's color in string format |
||
* GetName() -> s |
* GetName() -> s |
||
** Gets the activity's name |
** Gets the activity's name. Deprecated, use GetProperties() in new code |
||
** Returns: the activity's name |
** 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) |
|||
⚫ | |||
** Set the properties, which are as defined by GetProperties. Unchanged properties may be omitted. The type and ID cannot be changed. |
|||
* Join() -> nothing |
* Join() -> nothing |
||
** Joins the activity |
** Joins the activity |
||
** Returns: nothing, or an exception on error |
** 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 |
* GetJoinedBuddies() -> ao |
||
** Gets all buddies who are currently participating in this activity |
** Gets all buddies who are currently participating in this activity |
||
Line 70: | 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 |
|||
** 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== |
==Buddy Object== |
||
⚫ | |||
Object Path: /org/laptop/Sugar/Presence/Buddies/<br> |
Object Path: /org/laptop/Sugar/Presence/Buddies/<br> |
||
⚫ | |||
===Signals=== |
====Signals==== |
||
Refered objects passed in signals are specific to this buddy only. |
Refered objects passed in signals are specific to this buddy only. |
||
* IconChanged (ay: icon data) |
* IconChanged (ay: icon data) |
||
Line 82: | Line 138: | ||
* PropertyChanged (a{sv}: changed) |
* PropertyChanged (a{sv}: changed) |
||
===Methods=== |
====Methods==== |
||
* GetProperties() -> a{sv} |
* GetProperties() -> a{sv} |
||
** Gets all the general properties of the buddy |
** Gets all the general properties of the buddy |
||
Line 94: | Line 150: | ||
==Owner Object== |
==Owner Object== |
||
⚫ | |||
Object Path: /org/laptop/Sugar/Presence/Buddies/<br> |
Object Path: /org/laptop/Sugar/Presence/Buddies/<br> |
||
Owner is a subclass of Buddy, with additional methods for setting nickname, color, and buddy icon. |
Owner is a subclass of Buddy, with additional methods for setting nickname, color, and buddy icon. |
||
⚫ | |||
===Methods=== |
====Methods==== |
||
⚫ | |||
* SetIcon(ay: data) |
|||
** Sets the buddy's icon data |
** Sets the buddy's icon data |
||
** Returns: |
** Returns: |
||
* SetProperties(a{sv}: properties) |
* SetProperties(a{sv}: properties) -> nothing |
||
** 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 |
** Returns: InvalidPropertyError if a property is unrecognized its value is invalid |
||
[[Category:Sugar]] |
[[Category:Sugar]] |
||
[[Category:API]] |
|||
[[Category:Telepathy]] |
|||
[[Category:Collaboration]] |
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